poc orch docs, key-concepts- introduction, and dapp pages (#1132)

* poc orch docs, key-concepts- introduction, and dapp pages

* removed duplicate intro section from key concepts

* arrangement fixes, editorial, and syntax fixes for key concepts.

* type fix: added swap example link

* fixed ica glossary item typo

* added vow to glossary, and move vow tools to contract upgrade

* removed image

* added api page, cleanup

* added orchestration to main navigation

* added orchestration use case workflow 1

* added orchestration use case workflow 1

* WIP contract walkthroughs for swap and unbond

* WIP contract walkthrough sequence diagrams

* added mmd source

* typo fix

* doc updates for swap walkthrough

* removed link to asset kind, not created yet :)

* removed lorem

* removed uneccesary object access overview sentence

---------

Co-authored-by: mitdralla <[email protected]>

main/.vitepress/config.mjs

@@ -415,6 +415,35 @@ export default defineConfig({
             {
               text: 'Orchestration',
               link: '/guides/orchestration/',
+              collapsed: true,
+              items: [
+                {
+                  text: 'Key Concepts',
+                  link: '/guides/orchestration/getting-started/key-concepts',
+                },
+                {
+                  text: 'API',
+                  link: '/guides/orchestration/getting-started/api',
+                },
+                {
+                  text: 'Contract Walkthroughs',
+                  link: '/guides/orchestration/getting-started/contract-walkthroughs',
+                  items: [
+                    {
+                      text: 'Cross-Chain Swap Example',
+                      link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-swap',
+                    },
+                    {
+                      text: 'Cross-Chain Unbond Example',
+                      link: '/guides/orchestration/getting-started/contract-walkthrough/cross-chain-unbond',
+                    },
+                    {
+                      text: 'Orchestration Basics',
+                      link: '/guides/orchestration/getting-started/contract-walkthrough/orchestration-basics',
+                    }
+                  ]
+                },
+              ]
             },
             {
               text: 'JavaScript Framework',

main/.vitepress/theme/index.js

@@ -1,5 +1,5 @@
 // https://vitepress.dev/guide/custom-theme
-import { h } from 'vue'
+import { h, nextTick } from 'vue'
 import DefaultTheme from 'vitepress/theme'
 import './style.css'
 import '../styles/index.styl';

main/.vitepress/themeConfig/nav.js

@@ -74,7 +74,12 @@ export const nav = [
         collapsed: true,
         items: [],
       },
-
+      {
+        text: 'Orchestration',
+        link: '/guides/orchestration/',
+        collapsed: true,
+        items: [],
+      },
       {
         text: 'Zoe Smart Contract Framework',
         link: '/guides/zoe/',

main/glossary/index.md

@@ -337,8 +337,8 @@ Guide](https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/guide.md) for
 The Inter-Blockchain Communication protocol, used by blockchains to communicate with each other.
 For more details, see [What developers need to know about inter-blockchain communication](https://www.computerweekly.com/blog/Open-Source-Insider/What-developers-need-to-know-about-inter-blockchain-communication).
 
-## Intercahin Account (ICA)
 
+## Intercahin Account (ICA)
 Interchain Accounts are an [IBC](#ibc) feature used in Agoric's [Orchestration API](#orchestration) to enable an Agoric smart contract to control an account on another blockchain within the Cosmos ecosystem. This feature leverages the [Inter-Blockchain Communication (IBC)](#ibc) protocol to facilitate interactions and transactions across different blockchains seamlessly.
 
 ## Invitation
@@ -621,6 +621,14 @@ communicate with other vats and their objects and functions, but can only commun
 
 For more information, see the [Vat section in the Distributed JS Programming documentation](/guides/js-programming/#vats-the-unit-of-synchrony).
 
+The concept of a vat is metaphorically inspired by the philosophical experiment known as “Brain in a Vat.” This thought experiment, explored in philosophy, posits a scenario in which a brain is sustained in a vat and connected to a computer that simulates reality, raising questions about knowledge, reality, and perception. Similarly, in the context of distributed systems, a vat isolates and encapsulates its contents, maintaining strict boundaries on synchronous and asynchronous communication, much like the hypothetical brain’s isolated and controlled environment. For more details, see the Wikipedia page on [Brain in a Vat](https://en.wikipedia.org/wiki/Brain_in_a_vat).
+
+
+# Vow
+
+Vows are objects that represent promises that can be stored durably. Native promises are not compatible with Agoric's durable stores, which means that on the Agoric platform, such promises disconnect their clients when their creator vat is upgraded.  
+
+
 ## Wallet
 
 The overall place a party keeps their assets of all brands. For example, your wallet might contain 5 Quatloos

main/guides/orchestration/getting-started/api.md

@@ -0,0 +1,86 @@
+# Orchestration API
+
+The Agoric Orchestration API enables developers to seamlessly manage and interact with accounts across multiple blockchain networks, simplifying the complexities of cross-chain operations.
+
+See [Orchestration API Spec](https://agoric-sdk.pages.dev/modules/_agoric_orchestration)
+
+## Orchestrator Interface
+
+The `Orchestrator` interface provides a set of high-level methods to manage and interact with interchain accounts. Below are the primary methods:
+
+### `getChain`
+Retrieves the chain information and provides access to chain-specific methods.
+
+```javascript
+const chain = await orchestrator.getChain('chainName');
+```
+
+### makeLocalAccount
+Creates a new `LocalchainAccount`.
+
+```javascript
+const localAccount = await orchestrator.makeLocalAccount();
+```
+
+### getBrandInfo
+Returns information about a `denom`, including the equivalent local Brand, the chain where the denom is held, and the chain that issues the corresponding asset.
+
+```javascript
+const brandInfo = orchestrator.getBrandInfo('denom');
+```
+
+### asAmount
+Converts a denom amount to an `Amount` with a brand.
+
+```javascript
+const amount = orchestrator.asAmount({ denom: 'uatom', value: 1000n });
+```
+
+## OrchestrationAccount Interface
+Orchestration accounts provide high-level operations for managing accounts on remote chains. Below are the primary methods available:
+
+### getAddress
+Retrieves the address of the account on the remote chain.
+```javascript
+const address = await orchestrationAccount.getAddress();
+```
+
+### getBalances
+Returns an array of amounts for every balance in the account.
+
+```javascript
+const balances = await orchestrationAccount.getBalances();
+```
+
+### getBalance
+Retrieves the balance of a specific denom for the account.
+
+```javascript
+const balance = await orchestrationAccount.getBalance('uatom');
+```
+
+### send
+Transfers an amount to another account on the same chain. The promise settles when the transfer is complete.
+
+```javascript
+await orchestrationAccount.send(receiverAddress, amount);
+```
+
+### transfer
+Transfers an amount to another account, typically on another chain. The promise settles when the transfer is complete.
+
+```javascript
+await orchestrationAccount.transfer(amount, destinationAddress);
+```
+
+### transferSteps
+Transfers an amount to another account in multiple steps. The promise settles when the entire path of the transfer is complete.
+```javascript
+await orchestrationAccount.transferSteps(amount, transferMsg);
+```
+
+### deposit
+Deposits payment from Zoe to the account. For remote accounts, an IBC Transfer will be executed to transfer funds there.
+```javascript
+await orchestrationAccount.deposit(payment);
+```