Added orchestration overview and a code snippet

[ghost]

• Added an orchestration directory under main/guides/ and created index.md file.
• Added orchestration overview and a code snippet - this will probably be updated very soon

rendered:

• Orchestration Overview | Agoric Documentation

refs

• Docs Revamp | Dapp-Orchestration | Page 3 #930

[cloudflare-workers-and-pages]

Deploying documentation with    Cloudflare Pages

Latest commit:	705279f
Status:	✅  Deploy successful!
Preview URL:	https://09df7349.documentation-7tp.pages.dev
Branch Preview URL:	https://ms-addding-orchestartion-ind.documentation-7tp.pages.dev

View logs

[github-actions]

Cloudflare deployment logs are available here

[ghost]

@Jovonni Please review the text and suggest changes.

[dckc]

Good to see us getting started on this!

I have several technical comments.

[dckc]

technical: We don't use E like this in the orchestration API.

Suggested change

	const celestiaChain = E(orchestration).getChain('celestia');
	const celestiaChain = await orchestration.getChain('celestia');

Here's hoping we add an example to Orchestrator.getChain ... and clean up the huge inline chainInfo stuff there. cc @turadg

[ghost]

I fixed it as suggested but just wanted to double-check though because the following is a snippet from an example code (stakeIca.contract) in orchestration package:

const account = await E(orchestration).makeAccount(
      chainId,
      hostConnectionId,
      controllerConnectionId,
    );

@dckc Please confirm.

[dckc]

Good question.

E(orchestration).makeAccount(...) is a method call on an OrchestrationService, which is in a separate vat, so it needs E. In contrast, getChain is a method on Orchestrator, which is near (in the same vat).

Perhaps it would be more clear to use orchestrator in place of orchestration.

Here's hoping we manage to get the reference docs cleaned up soon:

https://agoric-sdk.pages.dev/interfaces/_agoric_orchestration.Orchestrator#getChain
https://agoric-sdk.pages.dev/types/_agoric_orchestration.OrchestrationService

[dckc]

technical

Suggested change

	const icaCelestia = await E(celestiaChain).createAccount();
	await E(icaOsmosis).send(icaCelestia.receiver, amount);
	await E(timerService).delay(6000n);
	return E(icaCelestia).delegate(amount, celestiaValidator);
	const icaCelestia = await celestiaChain.createAccount();
	await icaOsmosis.transfer(icaCelestia.getAddress(), amount);
	await E(timerService).delay(600n);
	return icaCelestia.delegate(celestiaValidator, amount);

• no E for chain objects, ica objects
• .receiver -> .getAddress()
• .send() only works within 1 chain. use .transfer() to do an IBC transfer across chains
• 6000n is not a typical time period. 600n is more typical: 10 minutes.
• Note: It's correct to use E() for timerService, but integration of E with the orchestration API is not yet available: asyncFlow should directly support E via promise handlers agoric-sdk#9299
• arguments to delegate go in the other order.

I'd really like us to use snippets of code that's tested in ci for examples such as this. Perhaps we can include https://github.com/Agoric/dapp-orchestration-basics as a git submodule and get snippets from there?

[ghost]

Fixed as suggested.

[dckc]

This seems relevant to #930; I went ahead and edited the PR description to say so.

[dckc]

My technical comments are addressed. (editorial too).

I'd like to defer to @mitdralla to approve.

[mitdralla]

This is a good first pass. I would like to see a few more inter-links to our documentation where possible - for example to SwingSet, even the glossary term vat and IBC. This landing page will also evolve over time as the API gets built out.

[mitdralla]

To make this more clear, let's get those links in: (SwingSet, the glossary term vat and IBC)

[ghost]

To make this more clear, let's get those links in: (SwingSet, the glossary term vat and IBC)

@mitdralla, Done.

[mitdralla]

looks good, approved

[Jovonni]

Also maybe we should make an outline for this section, so we can knock out the sections pretty quick at least a first pass. Should we maybe start from our curriculum? @mudassir-agoric