docs; orca dapp UI docs

amessbee · amessbee · commit fa8b5e0f2276 · 2024-10-09T18:14:57.000+05:00
diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs
@@ -137,10 +137,6 @@ export default defineConfig({
                   text: 'Send Anywhere Example',
                   link: '/guides/orchestration/contract-walkthrough/send-anywhere',
                 },
-                {
-                  text: 'Cross-Chain Swap Example',
-                  link: '/guides/orchestration/contract-walkthrough/cross-chain-swap',
-                },
                 {
                   text: 'Cross-Chain Unbond Example',
                   link: '/guides/orchestration/contract-walkthrough/cross-chain-unbond',
diff --git a/main/.vitepress/themeConfig/nav.js b/main/.vitepress/themeConfig/nav.js
@@ -24,10 +24,6 @@ export const nav = [
             text: 'Send Anywhere Example',
             link: '/guides/orchestration/contract-walkthrough/send-anywhere',
           },
-          {
-            text: 'Cross-Chain Swap Example',
-            link: '/guides/orchestration/contract-walkthrough/cross-chain-swap',
-          },
           {
             text: 'Cross-Chain Unbond Example',
             link: '/guides/orchestration/contract-walkthrough/cross-chain-unbond',
diff --git a/main/guides/orchestration/contract-walkthrough/index.md b/main/guides/orchestration/contract-walkthrough/index.md
@@ -1,6 +1,6 @@
 # Contract Walkthroughs
 
-This section is designed to provide detailed explanations and insights into example orchestration smart contracts.
+This section is designed to provide detailed explanations and insights into example Orchestration smart contracts.
 
 In this section, we will cover two primary contracts:
 
@@ -16,9 +16,9 @@ The "Send Anywhere" contract is a robust and secure solution for transferring as
 - Assets are securely held in a local account before being transferred.
 - Detailed logs are kept for transparency and error tracing.
 - The contract is resilient to failure, with built-in rollback mechanisms.
-- By using Agoric’s orchestration tools, this contract provides a secure way to facilitate cross-chain asset transfers.
+- By using Agoric’s Orchestration tools, this contract provides a secure way to facilitate cross-chain asset transfers.
 
-[See Contract Overview](/guides/orchestration/getting-started/contract-walkthrough/send-anywhere)
+[See Contract Overview](/guides/orchestration/contract-walkthrough/send-anywhere)
 
 ## Unbond Contract
 
@@ -28,4 +28,4 @@ The Unbond Contract focuses on the process of unbonding staked assets and perfor
 - Implementing delegation and undelegation logic.
 - Managing asynchronous operations and ensuring the completion of long-running processes.
 
-[See Contract Overview](/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond)
+[See Contract Overview](/guides/orchestration/contract-walkthrough/cross-chain-unbond)
diff --git a/main/guides/orchestration/contract-walkthrough/send-anywhere.md b/main/guides/orchestration/contract-walkthrough/send-anywhere.md
@@ -26,8 +26,8 @@ The contract begins by importing various modules and utilities necessary for its
 
 - **State management**: `makeSharedStateRecord` is imported to create and manage the state across contract incarnations.
 - **Type validation**: `AmountShape` and `InvitationShape` ensure that the contract works with correct data types, such as amounts and invitations.
-- **Orchestration utilities**: `withOrchestration` is imported to facilitate interactions with orchestration functions.
-- **Flows**: The orchestration flows for handling transfers are imported from `send-anywhere.flows.js` to be made available to Zoe.
+- **Orchestration utilities**: `withOrchestration` is imported to facilitate interactions with Orchestration functions.
+- **Flows**: The Orchestration flows for handling transfers are imported from `send-anywhere.flows.js` to be made available to Zoe.
 
 These imports set up the contract for the validation, orchestration, and execution of transfers through Zoe API.
 
@@ -204,4 +204,4 @@ The "Send Anywhere" contract is a robust and flexible solution for transferring
 - Assets are securely held in a local account before being transferred.
 - Detailed logs are kept for transparency and error tracing.
 - The contract is resilient to failure, with built-in rollback mechanisms.
-- By using Agoric’s orchestration tools, this contract provides a secure way to facilitate cross-chain asset transfers.
+- By using Agoric’s Orchestration tools, this contract provides a secure way to facilitate cross-chain asset transfers.
diff --git a/main/guides/orchestration/how-orch-works.md b/main/guides/orchestration/how-orch-works.md
@@ -2,7 +2,7 @@
 
 Orchestration relies on protocols and mechanisms that allow blockchains to
 communicate and transact with each other securely and efficiently. The primary
-objectives of orchestration are:
+objectives of Orchestration are:
 
 - **Interoperability:** Enabling different blockchain networks to interact and
   transact with one another.
@@ -124,10 +124,10 @@ asynchronous, makes it particularly well-suited for Interchain Accounts and
 Interchain Queries. When contracts on Agoric interact, the system is designed
 to handle cases where the other contract may reside on a remote machine or
 another blockchain. This inherent architecture allows Agoric to seamlessly
-control and manage Interchain Accounts, further enhancing the orchestration
+control and manage Interchain Accounts, further enhancing the Orchestration
 capabilities.
 
-By leveraging ICA and ICQ, blockchain orchestration becomes more flexible and
+By leveraging ICA and ICQ, Orchestration becomes more flexible and
 powerful, enabling direct, programmable interactions between blockchains. This
 unlocks a wide range of possibilities, from decentralized finance (DeFi) to
 supply chain management and beyond.
diff --git a/main/guides/orchestration/index.md b/main/guides/orchestration/index.md
@@ -22,7 +22,7 @@ The Orchestration API handles asynchronous tasks and complex workflows, includin
 
 ## Introduction to Orchestration API Flow
 
-The following sequence diagram provides a comprehensive overview of the orchestration process within the Agoric platform. This example illustrates the interaction between various components, highlighting how the orchestration library (`OrchLib`) facilitates cross-chain operations. This is a good first example to understand the flow of the Orchestration API, showing the steps involved in creating and managing cross-chain transactions.
+The following sequence diagram provides a comprehensive overview of the Orchestration process within the Agoric platform. This example illustrates the interaction between various components, highlighting how the Orchestration library (`OrchLib`) facilitates cross-chain operations. This is a good first example to understand the flow of the Orchestration API, showing the steps involved in creating and managing cross-chain transactions.
 
 <br/>
 <img src="/reference/assets/sequence-diagrams/orchestration-workflow-1.svg" width="100%" />
diff --git a/main/guides/orchestration/key-concepts.md b/main/guides/orchestration/key-concepts.md
@@ -1,6 +1,6 @@
 # Orchestration Key Concepts and APIs
 
-This document provides an overview of the fundamental concepts involved in building orchestration smart contracts,
+This document provides an overview of the fundamental concepts involved in building Orchestration smart contracts,
 focusing on Orchestrator Interface, Orchestration Accounts, and ChainHub.
 
 ## Orchestrator Interface
@@ -35,7 +35,7 @@ const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n });
 
 Orchestration accounts are a key concept in the Agoric Orchestration API, represented by the [`OrchestrationAccountI`](https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.OrchestrationAccountI)
 interface. These accounts provide high-level operations for managing accounts on remote chains, allowing seamless
-interaction and management of interchain accounts. The orchestration accounts abstract the complexity of interchain
+interaction and management of interchain accounts. The Orchestration accounts abstract the complexity of interchain
 interactions, providing a unified and simplified interface for developers.
 
 ### Account Creation
@@ -89,7 +89,7 @@ await orchestrationAccount.deposit(payment);
 ## ChainHub
 
 ChainHub is a centralized registry of chains, connections, and denoms that simplifies accessing and interacting with
-multiple chains, providing a unified interface for the orchestration logic to manage cross-chain operations effectively.
+multiple chains, providing a unified interface for the Orchestration logic to manage cross-chain operations effectively.
 A chainHub instance can be created using a call to `makeChainHub` that makes a new ChainHub in the zone (or in the heap
 if no [zone](/glossary/#zone) is provided). The resulting object is an [Exo](/glossary/#exo) singleton. It has no
 precious state. Its only state is a cache of queries to `agoricNames` and the info provided in registration calls. When
diff --git a/main/guides/orchestration/orchestration-basics/contract.md b/main/guides/orchestration/orchestration-basics/contract.md
@@ -1,13 +1,17 @@
 # Orca Contract Code Walkthrough
 
-This section provides a walkthrough of the Orca contract code, explaining its structure, key components, and functionality. The Orca contract is designed to manage orchestration accounts and fund them. It interacts with multiple chains and provides functionality for creating accounts and funding them. The code for the contract logic is in two files:
+This section provides a walkthrough of the Orca contract code, explaining its structure, key components, and
+functionality. The Orca contract is designed to manage Orchestration accounts and fund them. It interacts with multiple
+chains and provides functionality for creating accounts and funding them. The code for the contract logic is in two
+files:
 
-1. `orca.contract.js`
-2. `orca.flows.js`
+1. [`orca.contract.js`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/contract/src/orca.contract.js)
+2. [`orca.flows.js`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/contract/src/orca.flows.js)
 
 ## Walkthrough: `orca.contract.js`
 
-The `orca.contract.js` files brings in necessary dependencies and types from various Agoric packages. The flows import contains specific logic for the Orca contract operations.
+The `orca.contract.js` file brings in necessary dependencies and types from various Agoric packages. The `flows` import
+contains specific logic for the Orca contract offer handling operations.
 
 ```js
 import { AmountShape } from '@agoric/ertp';
@@ -21,7 +25,7 @@ import * as flows from './orca.flows.js';
 
 ### Type Definitions and Shapes
 
-These definitions create shapes for validating the structure of amounts and orchestration powers.
+The following definitions create shapes for validating the structure of `amount` and Orchestration powers.
 
 ```js
 const SingleAmountRecord = M.and(
@@ -40,7 +44,7 @@ const OrchestrationPowersShape = M.splitRecord({
 
 ### Main Contract Function
 
-This is the main contract function that sets up the contract's functionality.
+This is the main `contract` function that initializes and sets up the contract's functionality.
 
 ```js
 const contract = async (
@@ -55,7 +59,7 @@ const contract = async (
 
 Within the `contract` function, following actions are performed.
 
-- **Chain Registration**: Below section registers chains and their connections with the `chainHub`.
+- **Chain Registration**: Below code section registers chains and their connections with the `chainHub`.
 
 ```js
 const { chainDetails } = zcf.getTerms();
@@ -72,15 +76,18 @@ for (const [name, info] of entries(chainDetails)) {
 }
 ```
 
-- **Creating Account and Funding Functions**: These functions are created using the `orchestrateAll` helper, which sets up the necessary flow logic for account creation and funding.
+- **Creating Account and Funding Functions**: These functions are created using the `orchestrateAll` helper, which sets
+  up the necessary flow logic for account creation and funding but the logic is implemented in `orca.flows.js` file
+  ([discussed below](#walkthrough-orcaflowsjs)).
 
 ```js
 const { makeAccount, makeCreateAndFund } = orchestrateAll(flows, {
   localTransfer: zoeTools.localTransfer
 });
 ```
 
-- **Public Facet**: The public facet provides two methods: `makeAccountInvitation` creates an invitation to make an orchestration account, and `makeCreateAndFundInvitation` creates an invitation to make an account and fund it.
+- **Public Facet**: The public facet provides two methods: `makeAccountInvitation` creates an invitation to make an
+  Orchestration account, and `makeCreateAndFundInvitation` creates an invitation to make an account and fund it.
 
 ```js
 const publicFacet = zone.exo(
@@ -107,7 +114,8 @@ const publicFacet = zone.exo(
 
 ### `start` Function
 
-The start function is wrapped with `withOrchestration`, which provides additional orchestration setup and tools for the contract.
+The start function is wrapped with `withOrchestration`, which provides additional Orchestration setup and tools for the
+contract.
 
 ```js
 export const start = withOrchestration(contract);
@@ -116,7 +124,8 @@ harden(start);
 
 ## Walkthrough `orca.flows.js`
 
-This section provides a walkthrough of the `orca.flows.js` file, which contains flow functions for the Orca contract. The `orca.flows.js` file defines two main functions:
+This section provides a walkthrough of the `orca.flows.js` file, which contains flow functions for the Orca contract.
+The `orca.flows.js` file defines two main functions:
 
 1. `makeAccount`: Creates an account on a Cosmos chain.
 2. `makeCreateAndFund`: Creates an account on a Cosmos chain and funds it.
@@ -125,14 +134,21 @@ These functions are called by the Zoe vat when a user makes an offer using a cor
 
 ### `makeAccount` Function
 
-This function creates an account on a specified Cosmos chain. This function not only creates the account but also returns a continuing offer that allows the user to perform further actions like delegation, rewards withdrawl, and transfers. Here are the parameters of this function:
+This function creates an account on a specified Cosmos chain. This function not only creates the account but also
+returns a continuing offer that allows the user to perform further actions like delegation, rewards withdrawl, and
+transfers. Here are the parameters of this function:
+
+- `orch`: An Orchestrator instance parameter represents an instance of the `Orchestrator`, a powerful abstraction that
+  manages interactions with the blockchain. It provides methods to interact with different chains, create accounts, and
+  fetch chain information.
 
-- `orch`: An Orchestrator instance parameter represents an instance of the `Orchestrator`, a powerful abstraction that manages interactions with the blockchain. It provides methods to interact with different chains, create accounts, and fetch chain information.
 - `_ctx`: Unused context object
 - `seat`: A `ZCFSeat` instance. It holds a proposal object corresponding to the current offer.
-- `offerArgs`: An object containing `chainName` (that identifies the chain the orchestration account should be created on) and `denom`.
+- `offerArgs`: An object containing `chainName` (that identifies the chain the Orchestration account should be created on) and `denom`.
 
-The function validates the `offerArgs` to ensure it contains a `chainName`, retrieves the specified chain using `orch`, creates an account on the chain using `chain.makeAccount()`, and returns the account as a continuing offer. Below is the code of `makeAccount` after removing some debug information logging code.
+The function validates the `offerArgs` to ensure it contains a `chainName`, retrieves the specified chain using `orch`,
+creates an account on the chain using `chain.makeAccount()`, and returns the account as a continuing offer. Below is the
+code of `makeAccount` after removing some debug information logging code.
 
 ```js
 mustMatch(offerArgs, M.splitRecord({ chainName: M.string() }));
@@ -143,11 +159,14 @@ const chainAccount = await chain.makeAccount();
 return chainAccount.asContinuingOffer();
 ```
 
-Once the account is created, the function returns a continuing offer by calling `chainAccount.asContinuingOffer()`. This allows the user to perform further actions on the account, such as delegating tokens or withdrawing rewards, through subsequent offers.
+Once the account is created, the function returns a continuing offer by calling `chainAccount.asContinuingOffer()`. This
+allows the user to perform further actions on the account, such as delegating tokens or withdrawing rewards, through
+subsequent offers.
 
 ### `makeCreateAndFund` Function
 
-This function creates an account on a specified Cosmos chain and funds it. It accepts the same set of parameters as `make Account`. The function:
+This function creates an account on a specified Cosmos chain and funds it. It accepts the same set of parameters as
+`make Account`. The function:
 
 - Extracts the amount to be transferred from the seat's proposal, and retrieves both the Agoric chain and the specified target chain.
 - Fetches chain info and asset information.
@@ -159,27 +178,29 @@ This function creates an account on a specified Cosmos chain and funds it. It ac
 Below is the code of `makeCreateAndFund` after removing some debug information logging code.
 
 ```js
-  const { give } = seat.getProposal();
-  const [[_kw, amt]] = Object.entries(give);
-  const [agoric, chain] = await Promise.all([
-    orch.getChain('agoric'),
-    orch.getChain(chainName),
-  ]);
-  const localAccount = await agoric.makeAccount();
-  const remoteAccount = await chain.makeAccount();
-  const remoteAddress = await remoteAccount.getAddress();
-  await localTransfer(seat, localAccount, give);
-  await localAccount.transfer(
-    {
-      denom: 'ubld',
-      value: amt.value / 2n,
-    },
-    remoteAddress,
-  );
-  seat.exit();
-  return remoteAccount.asContinuingOffer();
+const { give } = seat.getProposal();
+const [[_kw, amt]] = Object.entries(give);
+const [agoric, chain] = await Promise.all([
+  orch.getChain('agoric'),
+  orch.getChain(chainName)
+]);
+const localAccount = await agoric.makeAccount();
+const remoteAccount = await chain.makeAccount();
+const remoteAddress = await remoteAccount.getAddress();
+await localTransfer(seat, localAccount, give);
+await localAccount.transfer(
+  {
+    denom: 'ubld',
+    value: amt.value / 2n
+  },
+  remoteAddress
+);
+seat.exit();
+return remoteAccount.asContinuingOffer();
 ```
 
-As in the previous case, the function returns a continuing offer by calling `remoteAccount.asContinuingOffer()` for further actions on the account.
+As in the previous case, the function returns a continuing offer by calling `remoteAccount.asContinuingOffer()` for
+further actions on the account.
 
-Apart from above mentioned logic, several trace calls are made to log the current state of the function. This is useful for debugging and ensuring that the function's inputs and intermediate states are correct.
+Apart from above mentioned logic, several trace calls are made to log the current state of the function. This is useful
+for debugging and ensuring that the function's inputs and intermediate states are correct.
diff --git a/main/guides/orchestration/orchestration-basics/index.md b/main/guides/orchestration/orchestration-basics/index.md
@@ -2,7 +2,9 @@
 
 To get started with developing using the Orchestration API, developers can make use of our [dapp-orchestration-basics](https://github.com/Agoric/dapp-orchestration-basics) template.
 
-Following the dApp pattern of our existing dapp templates, `dapp-orchestration-basics` contains both ui & contract directory within a single yarn workspace. In this walkthrough, we learn about the installation process, the contract code, and UI components of `dapp-orchestration-basics`.
+Following the dApp pattern of our existing dapp templates, `dapp-orchestration-basics` also contains a `contract` and a `ui`
+directory within a single yarn workspace. In this walkthrough, we learn about the installation process, the contract
+code, and UI components of `dapp-orchestration-basics`.
 
 1. [Installation and Deployment](installation)
 2. [Contract Code Walkthrough](contract)
diff --git a/main/guides/orchestration/orchestration-basics/installation.md b/main/guides/orchestration/orchestration-basics/installation.md
diff --git a/main/guides/orchestration/orchestration-basics/ui.md b/main/guides/orchestration/orchestration-basics/ui.md
