From 24a60b57848a9ea52a7bcd73746b8a444cbbd0c1 Mon Sep 17 00:00:00 2001 From: 0xPatrick Date: Thu, 5 Sep 2024 09:34:13 -0700 Subject: [PATCH] docs: orchestration usage Co-Author: Turadg Aleahmad --- packages/orchestration/USAGE.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 packages/orchestration/USAGE.md diff --git a/packages/orchestration/USAGE.md b/packages/orchestration/USAGE.md new file mode 100644 index 00000000000..a075656e196 --- /dev/null +++ b/packages/orchestration/USAGE.md @@ -0,0 +1,44 @@ +# Usage + +This document describes some example contracts and test suites showing how to use Orchestration. + +## Example contracts + +See [`src/examples`](src/examples) + + +| Contract Name | Status | Description | Features Used | +|---------------|-------------|---------------|--------| +| [auto-stake-it](/packages/orchestration/src/examples/auto-stake-it.contract.js) | Ready 🟢 | Sets up an IBC hook to automatically stake tokens on a remote chain received at a deposit address. | - `LocalOrchestrationAccount`
- `CosmosOrchestrationAccount`
- `Vtransfer` (IBC Hooks) | +| [basic-flows](/packages/orchestration/src/examples/basic-flows.contract.js) | Ready 🟢 | Creates an account on a remote chain and returns a continuing offer with all platform-provided invitationMakers. | - `CosmosOrchestrationAccount`
- `LocalOrchestrationAccount`| +| [query-flows](/packages/orchestration/src/fixtures/query-flows.contract.js) | Ready 🟢 | Test fixture that enables querying account balances on local and remote chains. | - `Chain`
- `LocalOrchestrationAccount`
- `CosmosOrchestrationAccount`
- Interchain Queries | +| [sendAnywhere](/packages/orchestration/src/examples/sendAnywhere.contract.js) | Ready 🟢 | Allows sending payments (tokens) over IBC to another chain. | - `LocalOrchestrationAccoun`t
- `Vtransfer` (IBC Hooks) | +| [stakeBld](/packages/orchestration/src/examples/stakeBld.contract.js) | Ready 🟢 | Returns a `LocalOrchestrationAccount` that can perform staking actions. | - `LocalOrchestrationAccount` | Ready 🟢 | +| [stakeIca](/packages/orchestration/src/examples/stakeIca.contract.js) | Ready 🟢 | Returns a `CosmosOrchestrationAccount` that can perform staking actions. | - `CosmosOrchestrationAccount` | Ready 🟢 | +| [staking-combinations](/packages/orchestration/src/examples/staking-combinations.contract.js) | Under Construction 🚧 | Combines actions into a single offer flow and demonstrates writing continuing offers. | - `CosmosOrchestrationAccount`
- `CombineInvitationMakers`
- Continuing Offers | +| [swap](/packages/orchestration/src/examples/swap.contract.js) | Under Construction 🚧 | Demonstrates asset swapping on an external chain. | - `CosmosOrchestrationAccount`
- `ChainHub` | +| [unbond](/packages/orchestration/src/examples/unbond.contract.js) | Under Construction 🚧 | Undelegates tokens for an ICA and liquid stakes them. | - `CosmosOrchestrationAccount` | + +## E2E Test Suites + +| Test Name | Description | Contract Used | Methods Used | +|-----------|-------------|---------------|--------------| +| [account-balance-queries](/multichain-testing/test/account-balance-queries.test.ts) | Tests balance querying on local and remote chains, verifying empty balance return for newly created accounts. | query-flows | - `orch.getChain()`
- `orch.makeAccount()`
- `orchAccount.getBalance()`
- `orchAccount.getBalances()` | +| [auto-stake-it](/multichain-testing/test/auto-stake-it.test.ts) | Tests the creation of Local and Cosmos orchestration accounts and the auto-delegation process via IBC transfer. | auto-stake-it | - `orch.getChain()`
- `chain.makeAccount()`
- `localOrchAccount.monitorTransfers()`
- `cosmosOrchAccount.delegate()` | +| [basic-flows](/multichain-testing/test/basic-flows.test.ts) | Verifies the creation of a remote chain account and the generation of a continuing offer with various invitationMakers. | basic-flows | - `orch.getChain()`
- `orch.makeAccount()` | +| [chain-queries](/multichain-testing/test/chain-queries.test.ts) | Tests balance queries via ICQ and local chain queries, including error handling for chains with ICQ disabled. | query-flows | - `orch.getChain()`
- `chain.query()` | +| [ica-channel-close](/multichain-testing/test/ica-channel-close.test.ts) | Tests ICA account deactivation and reactivation, and verifies channel closure processes for ICA and Transfer channels. | basic-flows | - `orch.getChain()`
- `orch.makeAccount()`
- `orchAccount.deactivate()`
- `orchAccount.reactivate()` | +| [send-anywhere](/multichain-testing/test/send-anywhere.test.ts) | Tests the process of sending payments over IBC, including account creation, deposit, and transfer operations. | sendAnywhere | - `orch.getChain()`
- `chain.getVBankAssetInfo()`
- `chain.makeAccount()`
- `localOrchAccount.makeAccount()`
- `localOrchAccount.deposit()`
- `localOrchAccount.transfer()`
- `zoeTools.localTransfer()` | +| [stake-ica](/multichain-testing/test/stake-ica.test.ts) | Verifies staking operations including delegation, reward withdrawal, and undelegation. | stakeIca | - `orch.getChain()`
- `orch.makeAccount()`
- `orchAccount.delegate()`
- `orchAccount.withdrawReward()`
- `orchAccount.undelegate()` | + +## Not Yet Tested + +| Contract Name | Not Yet Tested Features | +|---------------|--------------------------| +| [basic-flows](/packages/orchestration/src/examples/basic-flows.contract.js) | - `.send()`, `sendAll()` methods and `Send`, `SendAll` invitations ([#9193](https://github.com/Agoric/agoric-sdk/issues/9193))
- `CosmosOrchAccount.transfer()`, `Transfer` invitation ([#9193](https://github.com/Agoric/agoric-sdk/issues/9193)) | +| [sendAnywhere](/packages/orchestration/src/examples/sendAnywhere.contract.js) | - Multi-hop (PFM) transfers (not implemented in contract) ([#10006](https://github.com/Agoric/agoric-sdk/issues/10006)) | +| [stakeIca](/packages/orchestration/src/examples/stakeIca.contract.js) | - Redelegate
- WithdrawRewards (plural) (not implemented)
- StakingQueries (not implemented) ([#10016](https://github.com/Agoric/agoric-sdk/issues/10016))
- Staking Flows for LocalOrchAccount
- Written as async-flow ([#9838](https://github.com/Agoric/agoric-sdk/issues/9838)) | +| [stakeBld](/packages/orchestration/src/examples/stakeBld.contract.js) | - Everything*, created before e2e test suite
- Consider folding under generic "stake" contract, once [interfaces are the same](https://github.com/Agoric/agoric-sdk/blob/1976c502bcaac2e7d21f42b30447671a61053236/packages/orchestration/src/exos/local-orchestration-account.js#L487)| +| [swap](/packages/orchestration/src/examples/swap.contract.js) | - Everything - contract incomplete ([#8863](https://github.com/Agoric/agoric-sdk/issues/8863)) | +| [unbond](/packages/orchestration/src/examples/unbond.contract.js) | - Everything - contract incomplete ([#9782](https://github.com/Agoric/agoric-sdk/issues/9782)) | +|