9757 Orchestration docs timebox #10050

turadg · 2024-09-09T19:46:30Z

refs: #9757

Description

A bunch of docs improvements to get into the u17 release.

This doesn't do all the things specified in the ticket so leaves open:

Incomplete jsdocs for Orchestration API types, variables, methods and parameters #9757

Security Considerations

n/a

Scaling Considerations

n/a

Documentation Considerations

We'll need tutorial docs. I think some of the @example suggestions make more sense there.

Testing Considerations

CI

Upgrade Considerations

not yet deployed

cloudflare-workers-and-pages · 2024-09-09T19:48:37Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`220d4b2`
Status:	✅ Deploy successful!
Preview URL:	https://c8cf169f.agoric-sdk.pages.dev
Branch Preview URL:	https://9757-timebox.agoric-sdk.pages.dev

View logs

dckc

Pretty clearly forward progress.

The closest thing to a critical comment is on marking the agoricNames keys as internal.But it's conservative - we can expose it later.

dckc · 2024-09-09T19:49:15Z

package.json

@@ -32,7 +32,7 @@
    "prettier-plugin-jsdoc": "^1.3.0",
    "prettier-plugin-sh": "^0.14.0",
    "type-coverage": "^2.27.1",
-    "typedoc": "^0.26.4",
+    "typedoc": "^0.26.7",


are there any particular features that we're using from this release? or was this just housekeeping?

I notice it's less than a day old. For ref: c56c478

maybe hoping for better visibility support?

dckc · 2024-09-09T19:52:03Z

packages/orchestration/src/utils/start-helper.js

+ * const contract = (zcf, privateArgs, zone, tools) => { ... };
+ * export const start = withOrchestration(contract);
+ * ```
+ *


I don't see withOrchestration on https://9757-timebox.agoric-sdk.pages.dev/modules/_agoric_orchestration :-/

oh yeah, that got stalled: #9808

I'll try to solve that here

dckc · 2024-09-09T19:53:37Z

packages/orchestration/src/cosmos-api.ts

+/**
+ * Transactions for doing staking operations on an individual account.
+ *
+ * @see {@link https://docs.cosmos.network/main/build/modules/staking#messages x/staking messages}


a comma or something between the links would help.

it's a little hard to tell that there are 2 of them.

dckc · 2024-09-09T19:54:16Z

packages/orchestration/src/cosmos-api.ts

+ * Cosmos-specific methods to extend `OrchestrationAccountI`, parameterized
+ * by `CosmosChainInfo`.
+ *
+ * In particular, if the chain info includes a staking token, `StakingAccountActions`


use {@link StakingAccountActions}?

dckc · 2024-09-09T20:03:19Z

packages/orchestration/src/orchestration-api.ts

@@ -234,6 +234,9 @@ export interface OrchestrationAccountI {
  getPublicTopics: () => Promise<Record<string, ResolvedPublicTopic<unknown>>>;
 }

+/**
+ * An async-flow suitable for use in contracts using Orchestration


"async-flow" is a pretty opaque term here.

I suggest moving (most of) the "Orchestration flows" section of the README to here.

dckc · 2024-09-09T20:04:35Z

packages/orchestration/src/orchestration-api.ts

@@ -246,6 +246,7 @@ export interface OrchestrationFlow<CT = unknown> {
 * The type must be able to express transfers across different chains and transports.
 *
 * NOTE Expected to change, so consider an opaque structure.
+ * @internal


looks like you got this working. nice!

dckc · 2024-09-09T20:07:14Z

packages/orchestration/src/exos/chain-hub.js

+/**
+ * agoricNames key for ChainInfo hub
+ *
+ * @internal


These agoricNames keys don't seem internal to me. They show up all the way to clients via vstorage.

good point, I'll revert those. I still think they should go into an enum, but that can wait

dckc · 2024-09-09T20:08:07Z

packages/orchestration/src/exos/ica-account-kit.js

@@ -42,7 +41,9 @@ export const IcaAccountI = M.interface('IcaAccount', {
  reactivate: M.call().returns(VowShape),
 });

+// XXX none of these modifiers are working to exclude this type from api-docs


oh. so it's not yet working?

in some cases, no. maybe on types that are transitively included

dckc · 2024-09-09T20:10:40Z

packages/orchestration/src/cosmos-api.ts

-export type IBCConnectionInfo = {
+export interface IBCConnectionInfo {


I'd expect to use interfaces for things with methods, but this is an ordinary data structure. Why not leave it as a type alias?

I guess being able to refer to each property with a link is nice.

I read some perf docs recently: https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections

dckc · 2024-09-09T20:11:19Z

packages/orchestration/src/cosmos-api.ts

-export type CosmosAssetInfo = {
+export interface CosmosAssetInfo extends Record<string, unknown> {


likewise, seems fine as a type alias

0xpatrickdev · 2024-09-09T20:46:48Z

packages/orchestration/src/chain-info.js

 /** @import {NameAdmin} from '@agoric/vats'; */

-/** @typedef {CosmosChainInfo | EthChainInfo} ChainInfo */
+/**
+ * Info used to build a {@link Chain} object - naming, connections, etc.


nit: naming stuck out to me as something to improve. maybe:

Suggested change

* Info used to build a {@link Chain} object - naming, connections, etc.

* Info used to build a {@link Chain} object - channel, connection, and denom info.

0xpatrickdev · 2024-09-09T20:50:39Z

packages/orchestration/src/chain-info.js

@@ -78,12 +78,14 @@ const knownChains = /** @satisfies {Record<string, ChainInfo>} */ (
 * @internal
 */

+// TODO(#9572): include this in registerChain


0xpatrickdev · 2024-09-09T20:53:41Z

packages/orchestration/src/typeGuards.js

@@ -133,6 +134,7 @@ export const DenomAmountShape = { denom: DenomShape, value: M.bigint() };
 /** @type {TypedPattern<AmountArg>} */
 export const AmountArgShape = M.or(AmountShape, DenomAmountShape);

+/** @type {TypedPattern<RequestQuery>} */


RequestQuery['data'] is Uint8Array. Was going to suggest using TypedPattern<JsonSafe<RequestQuery>>, but we need to preserve RequestQuery['height']: bigint

thanks, I'll correct this

chore(deps): bump typedoc to 0.26.7

56fbf58

turadg added the bypass:integration Prevent integration tests from running on PR label Sep 9, 2024

turadg requested review from dckc and 0xpatrickdev September 9, 2024 19:46

turadg and others added 12 commits September 9, 2024 13:05

chore(deps): npx yarn-deduplicate

b8c6841

chore: update type-coverage

96bf8c3

docs: @example for withOrchestration

23ef07c

docs: StakingAccountQueries, StakingAccountActions, ...

901efc5

docs: ChainInfo

4a149cc

docs: CosmosInterchainService

da56653

docs: for ChainHubAdmin.registerChain

1d0d961

chore: export * from chain-hub-admin

ed3f2e6

docs: chainHubAdmin example

15fe11b

docs: vat-orchestration buildRootObject

48a325c

docs: OrchestrationAccount

eb5b978

docs: Orchestration methods

1f3fc93

turadg force-pushed the 9757-timebox branch from 666c99b to 97506a2 Compare September 9, 2024 20:05

dckc approved these changes Sep 9, 2024

View reviewed changes

0xpatrickdev approved these changes Sep 9, 2024

View reviewed changes

turadg added the automerge:rebase Automatically rebase updates, then merge label Sep 9, 2024

turadg added 9 commits September 9, 2024 21:08

docs: OrchestrationFlow

a7e1917

docs: Proto3Shape, AmountArgShape

47a4ff6

docs: mark internal, alpha symbols

54cc2b9

build: filter docs output (alpha, internal, private)

7b97301

chore: remove unnecessary exports

1af6135

docs: mark internal,private

c3df059

docs: additional descriptions

5d3a614

docs: ICQMsgShape

98103e9

chore(type): use interfaces

e34bf51

turadg added 3 commits September 9, 2024 21:08

chore: update type-coverage

cc4b382

feat: export withOrchestration

45fae2b

refactor(types): import OrchestrationPowers

220d4b2

turadg force-pushed the 9757-timebox branch from 177a355 to 220d4b2 Compare September 9, 2024 21:08

turadg mentioned this pull request Sep 9, 2024

export withOrchestration #9808

Closed

mergify bot merged commit 2e66067 into master Sep 9, 2024
79 checks passed

mergify bot deleted the 9757-timebox branch September 9, 2024 21:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

9757 Orchestration docs timebox #10050

9757 Orchestration docs timebox #10050

turadg commented Sep 9, 2024

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

edited

Loading

dckc left a comment

dckc Sep 9, 2024

dckc Sep 9, 2024

dckc Sep 9, 2024

turadg Sep 9, 2024

dckc Sep 9, 2024

dckc Sep 9, 2024

dckc Sep 9, 2024

turadg Sep 9, 2024

dckc Sep 9, 2024

dckc Sep 9, 2024

turadg Sep 9, 2024

dckc Sep 9, 2024

turadg Sep 9, 2024

turadg Sep 9, 2024

dckc Sep 9, 2024

dckc Sep 9, 2024

turadg Sep 9, 2024

dckc Sep 9, 2024

0xpatrickdev Sep 9, 2024

0xpatrickdev Sep 9, 2024

0xpatrickdev Sep 9, 2024

turadg Sep 9, 2024

		export type IBCConnectionInfo = {
		export interface IBCConnectionInfo {

		export type CosmosAssetInfo = {
		export interface CosmosAssetInfo extends Record<string, unknown> {

	* Info used to build a {@link Chain} object - naming, connections, etc.
	* Info used to build a {@link Chain} object - channel, connection, and denom info.

9757 Orchestration docs timebox #10050

9757 Orchestration docs timebox #10050

Conversation

turadg commented Sep 9, 2024

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

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

Deploying agoric-sdk with Cloudflare Pages

dckc 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

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

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

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

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

edited

Loading