diff --git a/_redirects b/_redirects
index db5cca4f3..1d99c0875 100644
--- a/_redirects
+++ b/_redirects
@@ -44,8 +44,18 @@
/guides/js-programming/ses/ses-guide.html https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/guide.md
/guides/js-programming/ses/ses-reference https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/reference.md
/guides/js-programming/ses/ses-reference.html https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/reference.md
+/guides/orchestration/getting-started/contract-walkthroughs /guides/orchestration/contract-walkthroughs
+/guides/orchestration/getting-started/contract-walkthroughs.html /guides/orchestration/contract-walkthroughs
+/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond /guides/orchestration/contract-walkthroughs/cross-chain-unbond
+/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond.html /guides/orchestration/contract-walkthroughs/cross-chain-unbond
+/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics /guides/orchestration/orchestration-basics
+/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics.html /guides/orchestration/orchestration-basics
+/guides/orchestration/getting-started/contract-walkthrough/send-anywhere /guides/orchestration/contract-walkthroughs/send-anywhere
+/guides/orchestration/getting-started/contract-walkthrough/send-anywhere.html /guides/orchestration/contract-walkthroughs/send-anywhere
+/guides/orchestration/getting-started/key-concepts /guides/orchestration/key-concepts
+/guides/orchestration/getting-started/key-concepts.html /guides/orchestration/key-concepts
/guides/wallet/api /reference/wallet-api/
-/guides/wallet/api.html /reference/wallet-api.html
+/guides/wallet/api.html /reference/wallet-api.html
/guides/wallet/api/* /reference/wallet-api/:splat
/platform /guides/platform/
/platform /guides/platform/
diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs
index 0878e2f00..f879b0af2 100644
--- a/main/.vitepress/config.mjs
+++ b/main/.vitepress/config.mjs
@@ -127,23 +127,37 @@ export default defineConfig({
items: [
{
text: 'Key Concepts and APIs',
- link: '/guides/orchestration/getting-started/key-concepts',
+ link: '/guides/orchestration/key-concepts',
},
{
text: 'Contract Walkthroughs',
- link: '/guides/orchestration/getting-started/contract-walkthroughs',
+ link: '/guides/orchestration/contract-walkthroughs/',
items: [
{
text: 'Send Anywhere Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/send-anywhere',
+ link: '/guides/orchestration/contract-walkthroughs/send-anywhere',
},
{
- text: 'Cross-Chain Swap Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap',
+ text: 'Cross-Chain Unbond Example',
+ link: '/guides/orchestration/contract-walkthroughs/cross-chain-unbond',
+ }
+ ]
+ },
+ {
+ text: 'Example Orchestration DApp',
+ link: '/guides/orchestration/orchestration-basics/',
+ items: [
+ {
+ text: 'Installation and Deployment',
+ link: '/guides/orchestration/orchestration-basics/installation',
},
{
- text: 'Cross-Chain Unbond Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond',
+ text: 'Orca Contract walkthrough',
+ link: '/guides/orchestration/orchestration-basics/contract',
+ },
+ {
+ text: 'UI Walkthrough',
+ link: '/guides/orchestration/orchestration-basics/ui',
}
]
},
diff --git a/main/.vitepress/themeConfig/nav.js b/main/.vitepress/themeConfig/nav.js
index 0f4cdf67f..0bbd2f63b 100644
--- a/main/.vitepress/themeConfig/nav.js
+++ b/main/.vitepress/themeConfig/nav.js
@@ -15,22 +15,35 @@ export const nav = [
},
{
text: 'Key Concepts and APIs',
- link: '/guides/orchestration/getting-started/key-concepts',
+ link: '/guides/orchestration/key-concepts',
},
{
text: 'Contract Walkthroughs',
items: [
{
text: 'Send Anywhere Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/send-anywhere',
+ link: '/guides/orchestration/contract-walkthroughs/send-anywhere',
},
{
- text: 'Cross-Chain Swap Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap',
+ text: 'Cross-Chain Unbond Example',
+ link: '/guides/orchestration/contract-walkthroughs/cross-chain-unbond',
+ }
+ ]
+ },
+ {
+ text: 'Example Orchestration DApp',
+ items: [
+ {
+ text: 'Installation and Deployment',
+ link: '/guides/orchestration/orchestration-basics/installation',
},
{
- text: 'Cross-Chain Unbond Example',
- link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond',
+ text: 'Orca Contract walkthrough',
+ link: '/guides/orchestration/orchestration-basics/contract',
+ },
+ {
+ text: 'UI Walkthrough',
+ link: '/guides/orchestration/orchestration-basics/ui',
}
]
},
diff --git a/main/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond.md b/main/guides/orchestration/contract-walkthroughs/cross-chain-unbond.md
similarity index 100%
rename from main/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond.md
rename to main/guides/orchestration/contract-walkthroughs/cross-chain-unbond.md
diff --git a/main/guides/orchestration/getting-started/contract-walkthroughs.md b/main/guides/orchestration/contract-walkthroughs/index.md
similarity index 59%
rename from main/guides/orchestration/getting-started/contract-walkthroughs.md
rename to main/guides/orchestration/contract-walkthroughs/index.md
index adacfab49..9d2d1e3ff 100644
--- a/main/guides/orchestration/getting-started/contract-walkthroughs.md
+++ b/main/guides/orchestration/contract-walkthroughs/index.md
@@ -1,12 +1,11 @@
# 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 three primary contracts:
+In this section, we will cover two primary contracts:
1. **Assets Transfer Contract**: A guide to `send-anywhere` contract that demonstrates a simple yet robust and secure way for cross-chain assets transfer.
-2. **Swap Contract**: A comprehensive guide to the process of swapping assets between different chains using the Agoric orchestration library.
-3. **Unbond Contract**: A detailed walkthrough of the unbonding and liquid staking process, highlighting the steps involved in managing cross-chain operations.
+2. **Unbond Contract**: A detailed walkthrough of the unbonding and liquid staking process, highlighting the steps involved in managing cross-chain operations.
Each walkthrough will include detailed explanations of the contract code, providing insights into the mechanics and best practices of smart contract development on the Agoric platform. By the end of these walkthroughs, you should have a solid understanding of how to utilize Agoric’s tools and libraries to create robust and efficient cross-chain smart contracts.
@@ -17,20 +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)
-
-## Swap Contract
-
-The Swap Contract demonstrates how to swap assets between the Agoric chain and another blockchain. This example covers:
-
-- Initializing and setting up the contract.
-- Creating and managing accounts on different chains.
-- Executing cross-chain asset transfers.
-- Handling errors and ensuring secure transactions.
-
-[See Contract Overview](/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap)
+[See Contract Overview](/guides/orchestration/contract-walkthroughs/send-anywhere)
## Unbond Contract
@@ -40,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-walkthroughs/cross-chain-unbond)
diff --git a/main/guides/orchestration/getting-started/contract-walkthrough/send-anywhere.md b/main/guides/orchestration/contract-walkthroughs/send-anywhere.md
similarity index 97%
rename from main/guides/orchestration/getting-started/contract-walkthrough/send-anywhere.md
rename to main/guides/orchestration/contract-walkthroughs/send-anywhere.md
index 860fc103a..a26184091 100644
--- a/main/guides/orchestration/getting-started/contract-walkthrough/send-anywhere.md
+++ b/main/guides/orchestration/contract-walkthroughs/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/getting-started/contract-walkthrough/cross-chain-swap.md b/main/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap.md
deleted file mode 100644
index a093fc545..000000000
--- a/main/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap.md
+++ /dev/null
@@ -1,259 +0,0 @@
-# Cross-Chain Swap Contract
-
-## Overview Diagram
-
-
-
-
-
-## Imports
-
-```js
-import { StorageNodeShape } from '@agoric/internal';
-import { TimerServiceShape } from '@agoric/time';
-import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
-import { deeplyFulfilled } from '@endo/marshal';
-import { M, objectMap } from '@endo/patterns';
-import { orcUtils } from '../utils/orc.js';
-import { withOrchestration } from '../utils/start-helper.js';
-```
-
-Importing Shapes and Utilities:
-
-- `StorageNodeShape` and `TimerServiceShape` are imported for validating the `privateArgs`.
-- `withdrawFromSeat` is a helper function from Zoe to withdraw funds from a seat.
-- `deeplyFulfilled` is a function that ensures that all promises within an object are resolved.
-- `M` are pattern-matching utilities, and `objectMap` is like `Array.map` but for properties of an object.
-- `orcUtils` is a utility library specific to orchestrating chain operations.
-- `withOrchestration` is a function that sets up orchestration.
-
-## Type Imports
-
-```js
-/**
- * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
- * @import {TimerService} from '@agoric/time';
- * @import {LocalChain} from '@agoric/vats/src/localchain.js';
- * @import {Remote} from '@agoric/internal';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
- * @import {NameHub} from '@agoric/vats';
- * @import {Zone} from '@agoric/zone';
- * @import {OrchestrationTools} from '../utils/start-helper.js';
- */
-```
-
-This includes type information to help with TypeScript or JSDoc annotations, which are useful for understanding the types used throughout the contract.
-
-## `stakeAndSwapFn` Offer Handler
-
-```js
-/**
- * @param {Orchestrator} orch
- * @param {object} ctx
- * @param {ZCF} ctx.zcf
- * @param {ZCFSeat} seat
- * @param {object} offerArgs
- * @param {Amount<'nat'>} offerArgs.staked
- * @param {CosmosValidatorAddress} offerArgs.validator
- */
-const stakeAndSwapFn = async (orch, { zcf }, seat, offerArgs) => {
-// ...
-```
-
-Function Parameters:
-
-- `orch`: The orchestrator object to manage interactions with chains/accounts.
-- `ctx`: Context object containing zcf.
-- `seat`: The seat representing the contract's position in the offer.
-- `offerArgs`: Arguments provided with the offer, including staked amount and validator address.
-
-```js
-const { give } = seat.getProposal();
-```
-
-Extracts the `give` part of the proposal from the seat. This includes what the user is offering to the contract.
-
-```js
-const omni = await orch.getChain('omniflixhub');
-const agoric = await orch.getChain('agoric');
-```
-
-Retrieves chain objects for omniflixhub (a remote chain) and agoric (the local chain) chains using the orchestrator.
-
-```js
-const [omniAccount, localAccount] = await Promise.all([
- omni.makeAccount(),
- agoric.makeAccount()
-]);
-```
-
-Creates accounts on both omniflixhub and agoric chains concurrently.
-
-```js
-const omniAddress = omniAccount.getAddress();
-```
-
-Retrieves the address of the omniAccount.
-
-## Depositing and Exiting
-
-```js
-// deposit funds from user seat to LocalChainAccount
-const payments = await withdrawFromSeat(zcf, seat, give);
-await deeplyFulfilled(
- objectMap(payments, payment => localAccount.deposit(payment))
-);
-seat.exit();
-```
-
-### Withdraw Funds
-
-Withdraws the funds specified in the give part of the proposal from the seat.
-
-### Deposit Funds
-
-Deposits the withdrawn payments into the local account.
-
-### Exit Seat
-
-The seat exits the offer, completing the offer being handled.
-
-## Building and Executing Swap Instructions
-
-```js
-// build swap instructions with orcUtils library
-const transferMsg = orcUtils.makeOsmosisSwap({
- destChain: 'omniflixhub',
- destAddress: omniAddress,
- amountIn: give.Stable,
- brandOut: '...',
- slippage: 0.03
-});
-```
-
-Parameters include destination chain, destination address, input amount, output brand, and slippage tolerance. In the `give` keyword record, the `Stable` keyword is expected to have the assets to trade.
-
-### Executing the `Swap` Instructions & Delegate
-
-Carries out the swap instructions using the results of `orcUtils.makeOsmosisSwap` above.
-
-```js
-await localAccount
- .transferSteps(give.Stable, transferMsg)
- .then(_txResult =>
- omniAccount.delegate(offerArgs.validator, offerArgs.staked)
- )
- .catch(e => console.error(e));
-```
-
-Transfers the stablecoins according to the swap instructions. On `transferSteps` being resolves, we delegate the staked amount to the specified validator on the omniflixhub chain.
-
-We log any errors that occur during the process.
-
-## Declaring `privateArgs` shape, and upgradeability
-
-```js
-/** @type {ContractMeta} */
-export const meta = {
- privateArgsShape: {
- agoricNames: M.remotable('agoricNames'),
- localchain: M.remotable('localchain'),
- orchestrationService: M.or(M.remotable('orchestration'), null),
- storageNode: StorageNodeShape,
- marshaller: M.remotable('marshaller'),
- timerService: M.or(TimerServiceShape, null)
- },
- upgradability: 'canUpgrade'
-};
-harden(meta);
-```
-
-This defines the shape of private arguments and the contract’s upgradability, and `harden` ensures that the metadata object is immutable.
-
-## `makeNatAmountShape` function
-
-```js
-/**
- * @param {Brand} brand must be a 'nat' brand, not checked
- * @param {NatValue} [min]
- */
-export const makeNatAmountShape = (brand, min) =>
- harden({ brand, value: min ? M.gte(min) : M.nat() });
-```
-
-Utility function to create a shape for amounts of the specified fungible brand. If a minimum value is provided, ensures the amount is greater than or equal to it.
-
-## `contract` Function
-
-The `contract` function when wrapped inside `withOrchestration` defines the [`start` function](#start-function) which is the entry point of the contract. The contract exports a `start` function [below](#start-function). It is merely a convention/convenience that we define a more abstract `contract` function here and pass it to `withOrchestration`. The arguments of this function are `zcf`, `privateAge`, `zone`, and `tools` for orchestration.
-
-```js
-/**
- * Orchestration contract to be wrapped by withOrchestration for Zoe
- *
- * @param {ZCF} zcf
- * @param {{
- * agoricNames: Remote;
- * localchain: Remote;
- * orchestrationService: Remote;
- * storageNode: Remote;
- * timerService: Remote;
- * marshaller: Marshaller;
- * }} privateArgs
- * @param {Zone} zone
- * @param {OrchestrationTools} tools
- */
-const contract = async (zcf, privateArgs, zone, { orchestrate }) => {
-```
-
-## Getting brands from Contract Terms
-
-```js
-const { brands } = zcf.getTerms();
-```
-
-This retrieves the brands specified in the contract terms.
-
-## Handler for swap and stake offers
-
-```js
-/** deprecated historical example */
-/**
- * @type {OfferHandler<
- * unknown,
- * { staked: Amount<'nat'>; validator: CosmosValidatorAddress }
- * >}
- */
-const swapAndStakeHandler = orchestrate('LSTTia', { zcf }, stakeAndSwapFn);
-```
-
-`swapAndStakeHandler` defines the offer handler for the swap and stake operation using [`stakeAndSwapFn` function](#stakeandswapfn-offer-handler).
-
-## Make Invitation and Create `publicFacet`
-
-```js
-const publicFacet = zone.exo('publicFacet', undefined, {
- makeSwapAndStakeInvitation() {
- return zcf.makeInvitation(
- swapAndStakeHandler,
- 'Swap for TIA and stake',
- undefined,
- harden({
- give: { Stable: makeNatAmountShape(brands.Stable, 1n) },
- want: {}, // XXX ChainAccount Ownable?
- exit: M.any()
- })
- );
- }
-});
-```
-
-Defines the `publicFacet` for the contract, which includes the method to make an `invitation` for users to swap stablecoins for TIA and stake, and returns the hardened public facet. Defining `publicFacet` with `zone.exo` makes it [remotely accessible](/glossary/#exo) and persistent through contract upgrades with a [durable `zone`](/glossary/#zone).
-
-## `start` Function
-
-```js
-export const start = withOrchestration(contract);
-```
-
-Defines the `start` function of the contract that is returned by a call to `withOrchestration` with [`contract` function](#contract-function) as a parameter. In essence `contract` function is the entry point or `start` function of this contract with some orchestration setup.
diff --git a/main/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics.md b/main/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics.md
deleted file mode 100644
index d4ab4683f..000000000
--- a/main/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# dApp Orchestration Basics
-
-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 folders within a single yarn workspace.
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/getting-started/key-concepts.md b/main/guides/orchestration/key-concepts.md
similarity index 96%
rename from main/guides/orchestration/getting-started/key-concepts.md
rename to main/guides/orchestration/key-concepts.md
index 411f356fa..c62debff8 100644
--- a/main/guides/orchestration/getting-started/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
new file mode 100644
index 000000000..5940717a0
--- /dev/null
+++ b/main/guides/orchestration/orchestration-basics/contract.md
@@ -0,0 +1,206 @@
+# 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:
+
+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)
+
+## `orca.contract.js`
+
+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';
+import { makeTracer } from '@agoric/internal';
+import { withOrchestration } from '@agoric/orchestration/src/utils/start-helper.js';
+import { ChainInfoShape } from '@agoric/orchestration/src/typeGuards.js';
+import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
+import { M } from '@endo/patterns';
+import * as flows from './orca.flows.js';
+```
+
+### Type Definitions and Shapes
+
+The following definitions create shapes for validating the structure of `amount` and Orchestration powers.
+
+```js
+const SingleAmountRecord = M.and(
+ M.recordOf(M.string(), AmountShape, { numPropertiesLimit: 1 }),
+ M.not(harden({}))
+);
+
+const OrchestrationPowersShape = M.splitRecord({
+ localchain: M.remotable('localchain'),
+ orchestrationService: M.remotable('orchestrationService'),
+ storageNode: M.remotable('storageNode'),
+ timerService: M.remotable('timerService'),
+ agoricNames: M.remotable('agoricNames')
+});
+```
+
+### Main Contract Function
+
+This is the main `contract` function that initializes and sets up the contract's functionality.
+
+```js
+const contract = async (
+ zcf,
+ privateArgs,
+ zone,
+ { orchestrateAll, zoeTools, chainHub }
+) => {
+ // ... (contract logic)
+};
+```
+
+Within the `contract` function, following actions are performed.
+
+- **Chain Registration**: Below code section registers chains and their connections with the `chainHub`.
+
+```js
+const { chainDetails } = zcf.getTerms();
+for (const [name, info] of entries(chainDetails)) {
+ const { connections = {} } = info;
+ trace('register', name, {
+ chainId: info.chainId,
+ connections: keys(connections)
+ });
+ chainHub.registerChain(name, info);
+ for (const [chainId, connInfo] of entries(connections)) {
+ chainHub.registerConnection(info.chainId, chainId, connInfo);
+ }
+}
+```
+
+- **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](#orca-flows-js)).
+
+```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.
+
+```js
+const publicFacet = zone.exo(
+ 'Orca Public Facet',
+ M.interface('Orca PF', {
+ makeAccountInvitation: M.callWhen().returns(InvitationShape),
+ makeCreateAndFundInvitation: M.callWhen().returns(InvitationShape)
+ }),
+ {
+ makeAccountInvitation() {
+ return zcf.makeInvitation(makeAccount, 'Make an Orchestration Account');
+ },
+ makeCreateAndFundInvitation() {
+ return zcf.makeInvitation(
+ makeCreateAndFund,
+ 'Make an Orchestration Account and Fund it',
+ undefined,
+ M.splitRecord({ give: SingleAmountRecord })
+ );
+ }
+ }
+);
+```
+
+### `start` Function
+
+The start function is wrapped with `withOrchestration`, which provides additional Orchestration setup and tools for the
+contract.
+
+```js
+export const start = withOrchestration(contract);
+harden(start);
+```
+
+## `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:
+
+1. `makeAccount`: Creates an account on a Cosmos chain.
+2. `makeCreateAndFund`: Creates an account on a Cosmos chain and funds it.
+
+These functions are called by the Zoe vat when a user makes an offer using a corresponding orca contract inivitation.
+
+### `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:
+
+- `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.
+
+```js
+mustMatch(offerArgs, M.splitRecord({ chainName: M.string() }));
+const { chainName } = offerArgs;
+seat.exit();
+const chain = await orch.getChain(chainName);
+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.
+
+### `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:
+
+- 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.
+- Creates accounts on both the Agoric chain (local) and the target chain (remote).
+- Transfers funds from the seat to the local account.
+- Transfers half of the received funds from the local account to the remote account.
+- Checks the balance of the remote account, and returns the remote account as a continuing offer.
+
+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();
+```
+
+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.
diff --git a/main/guides/orchestration/orchestration-basics/index.md b/main/guides/orchestration/orchestration-basics/index.md
new file mode 100644
index 000000000..ad635fdd7
--- /dev/null
+++ b/main/guides/orchestration/orchestration-basics/index.md
@@ -0,0 +1,11 @@
+# dApp Orchestration Basics
+
+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` 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)
+3. [UI Walkthrough](ui)
diff --git a/main/guides/orchestration/orchestration-basics/installation.md b/main/guides/orchestration/orchestration-basics/installation.md
new file mode 100644
index 000000000..19af4e937
--- /dev/null
+++ b/main/guides/orchestration/orchestration-basics/installation.md
@@ -0,0 +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 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
new file mode 100644
index 000000000..dfe5a3c9d
--- /dev/null
+++ b/main/guides/orchestration/orchestration-basics/ui.md
@@ -0,0 +1,44 @@
+# DApp User Interface
+
+Here, we will walkthrough the components making up the user interface for the Orchestration dApp.
+
+## `Orchestration`
+
+The [`Orchestration`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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`
+
+The [`AccountList`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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`
+
+The [`FetchBalances`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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).
+
+## `ChainSelector`
+
+The [`ChainSelector`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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`, and used in further interactions.
+
+## `MakeAccount`
+
+The [`MakeAccount`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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`
+
+The [`MakeOffer`](https://github.com/Agoric/dapp-orchestration-basics/blob/main/ui/src/components/Orchestration/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.