Improvements to Orchestration Key-Concepts Page #1201

amessbee · 2024-09-10T11:45:09Z

Here is a list of changes:

Fixed errors in the structure + grammar
Removed ICA figure from cosmos (theme looks out of place in our docs)
Merged Key Concepts and API pages as they had, somewhat, fluffy content.

Refs:

cloudflare-workers-and-pages · 2024-09-10T11:46:02Z

Deploying documentation with Cloudflare Pages

Latest commit:	`ecb07fb`
Status:	✅ Deploy successful!
Preview URL:	https://569ff001.documentation-7tp.pages.dev
Branch Preview URL:	https://ms-update-orch-concepts.documentation-7tp.pages.dev

View logs

github-actions · 2024-09-10T11:48:08Z

Cloudflare deployment logs are available here

dckc

I defer to @mitdralla and @Jovonni

mitdralla · 2024-09-11T05:15:59Z

The page (and docs) are really starting to come together. I have some feedback around the main navigation parents/children items. I think we could use more hierarchy to how the children links are organized - I think it is at the point where a category label could be helpful, and even further down the road a mega-menu type layout

For the side nav - "takeaway x:" seems unnecessary, I would just title and label it "Starting a Local Chain" and update the other items.

There is a lot of truncation on the right side nav, where the first words are more generic and the truncated part seems more important - consider cutting those words down so we can see the full title

Example: "Creating your Dapp from a Template" -> "Creating from a Template"
Example: "Starting the Dapp Smart Contract" -> "Starting the Smart Contract"

The page is long and could seem overwhelming for a Getting Started page. Consider adding in the copy up top "Get started in 5 steps" to help set some expectations.

or visit https://classic.yarnpkg.com/en/docs/install for more information -> or visit the official yarn package

I would guide them to the next logical location to hand hold them a bit more like "creating your first smart contract with our hello world example"

amessbee · 2024-09-11T08:59:02Z

@mitdralla thanks for your comments. They are very helpful and I or @mujahidkay will create a separate issue based on your feedback. My current PR is about a (key concepts and APIs) page in our new orchestration section. If you can also provide feedback on that it would be great. Below is a direct link to the updated page that needs to be reviewed:

Orchestration Key Concepts

Sorry for the confusion - I should have been clearer when I requested feedback. Looking forward.

main/guides/orchestration/getting-started/key-concepts.md

toliaqat · 2024-09-12T00:16:27Z

main/guides/orchestration/getting-started/key-concepts.md

 ```

-### ChainHub
+## ChainHub


Please make this section (ChainHub) consistent with previous two sections with regard to listing different APIs separately. For example I think you can add two sub-headings for registerChain and registerConnection in this section.

i agree, and take the opportunity to explain each. This is a good set of api functions though

@amessbee i'd say its good this is prob the only comment to address before merging.

toliaqat · 2024-09-12T00:19:58Z

main/guides/orchestration/getting-started/key-concepts.md


-### Orchestration Account
+## Interchain Account (ICA)


Also, please maket his section consistent by adding APIs subsections. Also currently it seems to be vague and marketing speak. For example, it is not clear to me at first what is ICA after all in the code example bellow.
Are omniAccount and localAccount ICA objects? If yes, then can you add getAddress, delegate, and transferSteps as API subsections in this ICA section?

I was thinking of removing this subsection but kept it for now. I don't understand it well enough to be certain, but I believe we do not use the ICA in the code that is externally accessible to the developers. Rather we use the orchestration account that I already explain above.

mitdralla · 2024-09-12T05:04:17Z

One more item which is minor - there is a missing space: "asAmountconverts a denom amount to an Amount with a brand."

turadg · 2024-09-24T14:21:50Z

Removing myself. This is DevRel purview.

toliaqat

Looks very good. Thanks for updating this page. I am approving from the editorial side. From the technical side, @Jovonni can have a quick look. If there are any minor technical issues, I would request to make subsequent PRs after merging this.

main/guides/orchestration/getting-started/key-concepts.md

mujahidkay · 2024-09-25T09:45:50Z

main/guides/orchestration/getting-started/key-concepts.md

+### Registration APIs
+
+- `registerChain` register a new chain with `chainHub`. The name will override a name in well known chain names. If a
+  durable zone was not provided, registration will not survive a reincarnation of the vat, and will have to be


I was able to follow the flow of these docs up until i read reincarnation of the vat especially since we haven't discussed it in orchestration docs before. What exactly is it? I think everything after the first sentence should be additional info presented in a tip section

IIRC "incarnation" represents before & after an upgrade.

After an upgrade you have a new incarnation. Maybe think of "version" when you see this.

Before an upgrade, the vat may be incarnation # 1, and then after an upgrade, the vat may be incarnation # 2

main/guides/orchestration/getting-started/key-concepts.md

mujahidkay

Great work! Please consider squashing the recent commits into an appropriate parent commit

Jovonni

left a few comments, its coming together nicely

Jovonni · 2024-09-25T15:49:06Z

main/guides/orchestration/getting-started/key-concepts.md


-### Interchain Account (ICA)


is there a reason why we are removing all education on interchain accounts? would like to understand this decision. If the team supports it then so be it, but I've found developers usually don't have an understanding on what an ICA is.

Although it can still be debated whether or not its useful, we have found it useful to explain it to them, and why its important. Other than that, orchestration accounts seem like magic.

main/guides/orchestration/getting-started/key-concepts.md

Jovonni · 2024-09-25T15:50:48Z

main/guides/orchestration/getting-started/key-concepts.md


-A key advantage of ICAs is that they make accounts on other chains look like any other (remotable) object. When a contract creates an ICA, it has sole access to and control over the account but can delegate certain forms of access to its clients.


any reason we are removing this?

Jovonni · 2024-09-25T15:53:30Z

main/guides/orchestration/getting-started/key-concepts.md


-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 interactions, providing a unified and simplified interface for developers.
+```javascript
+const [agoric, remoteChain] = await Promise.all([


not sure its helpful, but I find myself being asked, "what does promise.all do?" more often that I expected when showing this 👀

Jovonni · 2024-09-25T15:56:58Z

main/guides/orchestration/getting-started/key-concepts.md


 - `getAddress` retrieves the address of the account on the remote chain.

 ```javascript
 const address = await orchestrationAccount.getAddress()
 ```

-**2. Balance Management**
+### Balance Management


What is happening under the hood here, is IF we invoke getBalance on an remote account, this is actually an Interchain Query (ICQ). We can probably take the opportunity to briefly explain this here if this is the first time they see it.

Example from orch dapp contract:

const remoteChainBalance = await remoteAccount.getBalance('uosmo');

Jovonni · 2024-09-25T15:57:52Z

main/guides/orchestration/getting-started/key-concepts.md

 ```

-### ChainHub
+## ChainHub


i agree, and take the opportunity to explain each. This is a good set of api functions though

amessbee · 2024-09-26T05:32:27Z

@Jovonni thanks a lot for detailed review and comments. In essence, what we are doing here, everything that is not absolutely necessary for devs and posting it in a separate page: PR #1209.
We want this page to be magical and really abstract out all the details, conveying the message that if you need to orchestrate it is as simple as calling getChain, makeAccount, and then tansfer for you and Agoric will take care of everything under-the-hood, and BTW if you need to know what's going on under-the-hood, here is an other page with details.

WDYT?

Jovonni

LGTM 🚀 , this is the only thing to address:
https://github.com/Agoric/documentation/pull/1201/files#r1755891367

Jovonni · 2024-09-26T14:59:17Z

main/guides/orchestration/getting-started/key-concepts.md

 ```

-### ChainHub
+## ChainHub


@amessbee i'd say its good this is prob the only comment to address before merging.

amessbee · 2024-09-27T03:29:08Z

LGTM 🚀 , this is the only thing to address: https://github.com/Agoric/documentation/pull/1201/files#r1755891367

@Jovonni this comment by @toliaqat has already been addressed - if you look at the file chainHub section already has two subsections. Let me know if there are any further comments.

Co-authored-by: Mujahid Khan <[email protected]> Co-authored-by: Mujahid Khan <[email protected]> Co-authored-by: Mujahid Khan <[email protected]>

amessbee marked this pull request as ready for review September 10, 2024 14:18

amessbee changed the title ~~Improvements to Orchestration Key-Concepts Page --WIP--~~ Improvements to Orchestration Key-Concepts Page Sep 10, 2024

amessbee requested review from toliaqat, dckc, Jovonni and mujahidkay September 10, 2024 14:19

dckc requested a review from mitdralla September 10, 2024 14:26

dckc reviewed Sep 10, 2024

View reviewed changes

LuqiPan assigned mitdralla Sep 11, 2024

toliaqat requested changes Sep 12, 2024

View reviewed changes

amessbee force-pushed the ms/update-orch-concepts branch from 410ad28 to 1b0bf9c Compare September 12, 2024 10:22

amessbee requested a review from toliaqat September 12, 2024 14:16

mujahidkay mentioned this pull request Sep 13, 2024

Structural Updates to Docs #1207

Open

amessbee self-assigned this Sep 16, 2024

amessbee mentioned this pull request Sep 23, 2024

(docs): Remove makeLocalAccount #1208

Open

amessbee requested a review from rowgraus September 23, 2024 16:03

amessbee force-pushed the ms/update-orch-concepts branch 2 times, most recently from d90ef38 to 9550bc3 Compare September 24, 2024 04:01

amessbee requested a review from turadg September 24, 2024 05:01

amessbee force-pushed the ms/update-orch-concepts branch 2 times, most recently from ea29202 to d80469b Compare September 24, 2024 05:05

turadg removed their request for review September 24, 2024 14:21

toliaqat removed the request for review from rowgraus September 24, 2024 18:31

toliaqat approved these changes Sep 25, 2024

View reviewed changes

mujahidkay reviewed Sep 25, 2024

View reviewed changes

amessbee force-pushed the ms/update-orch-concepts branch from d0ba308 to 3b38b50 Compare September 25, 2024 10:27

mujahidkay approved these changes Sep 25, 2024

View reviewed changes

Jovonni reviewed Sep 25, 2024

View reviewed changes

Jovonni self-requested a review September 26, 2024 14:51

Jovonni requested changes Sep 26, 2024

View reviewed changes

amessbee requested a review from Jovonni September 30, 2024 05:04

amessbee force-pushed the ms/update-orch-concepts branch 3 times, most recently from 5ac83ac to 6914698 Compare September 30, 2024 16:20

Jovonni approved these changes Oct 1, 2024

View reviewed changes

amessbee force-pushed the ms/update-orch-concepts branch from 6914698 to f4e2d72 Compare October 2, 2024 06:42

amessbee mentioned this pull request Oct 2, 2024

Updating Page: How-Does-Orchestration-Work #1209

Merged

amessbee and others added 4 commits October 2, 2024 11:49

docs: structural improvements to key-concepts.md

c2cf578

chore: merged key concepts and API in orch

44dd104

chore: update account creation section

50cf12e

Co-authored-by: Mujahid Khan <[email protected]> Co-authored-by: Mujahid Khan <[email protected]> Co-authored-by: Mujahid Khan <[email protected]>

chore: simplify registerChain

ecb07fb

amessbee force-pushed the ms/update-orch-concepts branch from f4e2d72 to ecb07fb Compare October 2, 2024 06:50

amessbee merged commit 20a3ecf into main Oct 2, 2024
6 checks passed

amessbee deleted the ms/update-orch-concepts branch October 2, 2024 07:00

This was referenced Oct 2, 2024

getting-started/api.html shows 404 #1224

Closed

chore: fix deadlink in nav + remove duplicate sidebar orch entry #1226

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to Orchestration Key-Concepts Page #1201

Improvements to Orchestration Key-Concepts Page #1201

amessbee commented Sep 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 10, 2024 •

edited

Loading

github-actions bot commented Sep 10, 2024 •

edited

Loading

dckc left a comment

mitdralla commented Sep 11, 2024

amessbee commented Sep 11, 2024

toliaqat Sep 12, 2024

Jovonni Sep 25, 2024

Jovonni Sep 26, 2024

toliaqat Sep 12, 2024

amessbee Sep 12, 2024

mitdralla commented Sep 12, 2024

turadg commented Sep 24, 2024

toliaqat left a comment

mujahidkay Sep 25, 2024

Jovonni Sep 25, 2024

mujahidkay left a comment

Jovonni left a comment

Jovonni Sep 25, 2024

Jovonni Sep 25, 2024

Jovonni Sep 25, 2024

Jovonni Sep 25, 2024

Jovonni Sep 25, 2024

amessbee commented Sep 26, 2024

Jovonni left a comment

Jovonni Sep 26, 2024

amessbee commented Sep 27, 2024


		A key advantage of ICAs is that they make accounts on other chains look like any other (remotable) object. When a contract creates an ICA, it has sole access to and control over the account but can delegate certain forms of access to its clients.

Improvements to Orchestration Key-Concepts Page #1201

Improvements to Orchestration Key-Concepts Page #1201

Conversation

amessbee commented Sep 10, 2024 • edited Loading

cloudflare-workers-and-pages bot commented Sep 10, 2024 • edited Loading

Deploying documentation with Cloudflare Pages

github-actions bot commented Sep 10, 2024 • edited Loading

dckc left a comment

Choose a reason for hiding this comment

mitdralla commented Sep 11, 2024

amessbee commented Sep 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mitdralla commented Sep 12, 2024

turadg commented Sep 24, 2024

toliaqat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mujahidkay left a comment

Choose a reason for hiding this comment

Jovonni left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amessbee commented Sep 26, 2024

Jovonni left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amessbee commented Sep 27, 2024

amessbee commented Sep 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Sep 10, 2024 •

edited

Loading

github-actions bot commented Sep 10, 2024 •

edited

Loading