docs; orca dapp UI docs

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`.
 
-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.
@@ -180,6 +199,8 @@ Below is the code of `makeCreateAndFund` after removing some debug information l
   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.

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)

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.

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 dApp orchestration.
+
+## 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.