From 7731143e67142e742cdd916b68c02d922204aca9 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 9 Jul 2024 17:04:54 +0500 Subject: [PATCH 1/3] docs: provideOrchestration API page --- .../orchestration/provideOrchestration.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 main/guides/orchestration/provideOrchestration.md diff --git a/main/guides/orchestration/provideOrchestration.md b/main/guides/orchestration/provideOrchestration.md new file mode 100644 index 000000000..05dcc7563 --- /dev/null +++ b/main/guides/orchestration/provideOrchestration.md @@ -0,0 +1,82 @@ +# provideOrchestration API Documentation + +## Overview +The `provideOrchestration` function is a helper utility designed for setting up orchestration +tools and resources required by a contract within the Agoric ecosystem. This function +initializes various orchestration components and returns an object containing these tools, +which can then be used to facilitate complex interchain interactions and management. + +## Function Signature + +```javascript +export const provideOrchestration = ( + zcf, + baggage, + remotePowers, + marshaller +) => { + // Function body +}; +``` + +## Parameters + +- **zcf**: Zoe Contract Facet. Provides access to Zoe-specific contract functionality. +- **baggage**: Persistent storage for contract data, allowing state retention across contract invocations. +- **remotePowers**: An object containing various remote services and utilities required for orchestration. This includes: + - `localchain`: Remote object for interacting with the local blockchain. + - `orchestrationService`: Remote object for the interchain orchestration service. + - `storageNode`: Remote object for persistent storage. + - `timerService`: Remote object for scheduling and timers. + - `agoricNames`: Remote object for accessing Agoric names. +- **marshaller**: Utility for data serialization and deserialization. + +## Returns + +An object containing the initialized orchestration tools and resources, including the zone, chain hub, and various orchestration utilities. + +## Detailed Description + +After setting up a test jig, allowing for testing and debugging with access to the `baggage`, the `provideOrchestration` function performs the following steps: + +1. **Create Zones**: + - Initializes a durable zone using the provided baggage for state management. + - Creates several sub-zones for organizing different aspects of the orchestration process, such as asyncFlow, contract, orchestration, and vows. + +2. **Initialize Chain Hub and Vow Tools**: + - Initializes the chain hub using `agoricNames`. + - Prepares vow tools within the vows sub-zone. + +3. **Prepare Recorder Kit Makers**: + - Prepares the recorder kit makers with the provided baggage and marshaller. + +4. **Prepare Local Orchestration Account Kit**: + - Sets up the local orchestration account kit with the required components, including the zone, recorder kit, ZCF, timer service, vow tools, and chain hub. + - Prepares async flow tools using the asyncFlow sub-zone and vow tools. + - Prepares the Cosmos orchestration account using the orchestration sub-zone, recorder kit, vow tools, and ZCF. + - Sets up the remote chain facade using the orchestration sub-zone, Cosmos orchestration account, orchestration service, storage node, timer service, and vow tools. + - Sets up the local chain facade using the orchestration sub-zone, local orchestration account kit, local chain, storage node, orchestration service, timer service, and vow tools. + +5. **Return the Orchestration Tools**: + - Constructs the orchestration facade with the provided components and additional remote powers. + - Returns an object containing the facade, chain hub, vow tools, and zone. + + +## Usage with `withOrchestration` + +The `provideOrchestration` function is often used in conjunction with the `withOrchestration` higher-order function to enhance contract functions with orchestration capabilities, ensuring that the necessary tools are available for managing interchain interactions effectively. Here is a typical usage: + +```javascript + +export const withOrchestration = + contractFn => async (zcf, privateArgs, baggage) => { + const { zone, ...tools } = provideOrchestration( + zcf, + baggage, + privateArgs, + privateArgs.marshaller, + ); + return contractFn(zcf, privateArgs, zone, tools); + }; +harden(withOrchestration); +``` From 0f9eb572552b69dab30c87cc894e59cbd3df7d77 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Tue, 9 Jul 2024 18:18:25 +0500 Subject: [PATCH 2/3] chore: provideOrchestration link in the left panel --- main/.vitepress/config.mjs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index f067830c6..988757ecb 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -415,6 +415,12 @@ export default defineConfig({ { text: 'Orchestration', link: '/guides/orchestration/', + items: [ + { + text: 'provideOrchestration', + link: '/guides/orchestration/provideOrchestration', + }, + ], }, { text: 'JavaScript Framework', From b66321ce262df86a98ae091c1785fa3011d8ccb6 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Fri, 26 Jul 2024 17:12:59 +0500 Subject: [PATCH 3/3] fix: order in config.mjs --- main/.vitepress/config.mjs | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index 58bf2af2c..b825338c0 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -415,12 +415,6 @@ export default defineConfig({ { text: 'Orchestration', link: '/guides/orchestration/', - items: [ - { - text: 'provideOrchestration', - link: '/guides/orchestration/provideOrchestration', - }, - ], collapsed: true, items: [ { @@ -449,6 +443,10 @@ export default defineConfig({ } ] }, + { + text: 'provideOrchestration', + link: '/guides/orchestration/provideOrchestration', + }, ] }, {