From fa8b5e0f2276aee44adf57934a0ca1e53311ba88 Mon Sep 17 00:00:00 2001 From: Mudassir Shabbir Date: Mon, 7 Oct 2024 16:52:43 +0500 Subject: [PATCH] docs; orca dapp UI docs --- main/.vitepress/config.mjs | 4 - main/.vitepress/themeConfig/nav.js | 4 - .../contract-walkthrough/index.md | 8 +- .../contract-walkthrough/send-anywhere.md | 6 +- main/guides/orchestration/how-orch-works.md | 6 +- main/guides/orchestration/index.md | 2 +- main/guides/orchestration/key-concepts.md | 6 +- .../orchestration-basics/contract.md | 97 +++++++++++-------- .../orchestration-basics/index.md | 4 +- .../orchestration-basics/installation.md | 4 +- .../orchestration/orchestration-basics/ui.md | 50 ++++++++++ 11 files changed, 129 insertions(+), 62 deletions(-) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index f2691142e..3e51f0121 100644 --- 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 index c09cd340c..bbed08bbf 100644 --- 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 index f3ff565a5..203384dcb 100644 --- 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 index 860fc103a..a26184091 100644 --- 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 index b72596447..1993d23dd 100644 --- 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 index 34083a2be..59f31d432 100644 --- 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.
diff --git a/main/guides/orchestration/key-concepts.md b/main/guides/orchestration/key-concepts.md index 411f356fa..c62debff8 100644 --- 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 index 4c87afe5a..4f1068f96 100644 --- 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,7 +76,9 @@ 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, { @@ -80,7 +86,8 @@ const { makeAccount, makeCreateAndFund } = orchestrateAll(flows, { }); ``` -- **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 index 02daa228f..ad635fdd7 100644 --- 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 index 60237a63b..19af4e937 100644 --- a/main/guides/orchestration/orchestration-basics/installation.md +++ b/main/guides/orchestration/orchestration-basics/installation.md @@ -1,3 +1,5 @@ # Installation and Deployment -The dApp implements a smart contract that can be installed and deployed on any Agoric testnet. Since, the contract interacts with remote chains, we need to a multichain environment - see [Agoric Multichain-Testing]() for details. Follow in the instructions in [dApp Readme]() to install, deploy and interact with the dApp on your local machine. +The dApp implements a smart contract that can be installed and deployed on any Agoric testnet. Since, the contract +interacts with the remote chains, we need a multichain environment for testing it on local network. [Agoric Multichain-Testing](https://github.com/Agoric/agoric-sdk/tree/master/multichain-testing) provides such an environment to test Orchestration based contracts. +Follow the instructions in [dApp Readme](https://github.com/Agoric/dapp-orchestration-basics/blob/main/README.md) to install, deploy and interact with the dApp on your local machine. diff --git a/main/guides/orchestration/orchestration-basics/ui.md b/main/guides/orchestration/orchestration-basics/ui.md index e69de29bb..db1331b97 100644 --- a/main/guides/orchestration/orchestration-basics/ui.md +++ b/main/guides/orchestration/orchestration-basics/ui.md @@ -0,0 +1,50 @@ +# DApp User Interface + +Here, we will walkthrough the components making up the user interface for the Orchestration dApp. + +## Orchestration.tsx + +The `Orchestration.tsx` component serves as the main controller for the Orchestration dApp's user interface. It manages +the state and interactions required for users to create accounts, manage their balances, and perform various blockchain +transactions such as deposits, withdrawals, staking, and unstaking. + +## AccountList.tsx + +The `AccountList.tsx` component is responsible for displaying the list of user accounts and their associated balances in +various native denoms. It presents account information in a structured and user-friendly format, allowing users to view +and interact with their Orchestration Accounts directly. + +## FetchBalances.tsx + +The `FetchBalances.tsx` component is responsible for retrieving the balances of user accounts from different +blockchains. It interacts with the local RPC endpoints to fetch balance data for addresses on supported chains (for +Osmosis and Agoric). + +## RpcEndpoints.tsx + +The `RpcEndpoints.tsx` component provides a convenient place to manage RPC endpoints for different chains, including +your local agoric instance, to be used by different components. This component is used by other components, like +`FetchBalances.tsx`, to interact with the correct blockchain network. + +## ChainSelector.tsx + +The `ChainSelector.tsx` component provides a basic UI element for users to select the Cosmos chain they want to interact +with. The selected chain is passed back to the parent component, `Orchestration.tsx`, and used in further interactions. + +## `MakeAccount.tsx` + +The `MakeAccount.tsx` component provides a user interface for managing interchain accounts on the Agoric blockchain. It +allows users to create new accounts on selected chains (like Osmosis or Agoric), fetch and display balances of these +accounts, and perform actions such as deposit. The component interacts with the Agoric wallet to make offers and uses +RPC endpoints to retrieve account balances, incorporating loading states and notifications to enhance the user +experience. + +## `MakeOffer.tsx` + +The `MakeOffer.tsx` component defines an asynchronous function `makeOffer` that facilitates making an offer through the +Agoric wallet. It first checks if a `selectedChain` is provided and retrieves the necessary contract instance +(specifically 'orca') and the `BLD` brand from the contract store. The function then constructs an offer where it gives +a deposit of `1000` units of `BLD`. It initiates the offer using the wallet's `makeOffer` method, providing callbacks to +handle various offer statuses such as 'error', 'accepted', 'refunded', and 'done'. Throughout the process, it updates +the loading state, toggles modals, sets status texts, and adds notifications to keep the user informed about the offer's +progress and outcome.