From d129b465f654f16369319087b1dd0fa41c7965a3 Mon Sep 17 00:00:00 2001 From: Igoric Bot <301173210+igoricbot@users.noreply.github.com> Date: Thu, 24 Sep 2026 19:54:57 +0000 Subject: [PATCH] docs: refresh getting-started onboarding cluster for current agoric-sdk Node.js requirement was pinned to the EOL v18.18.0; bump to v22.11.0 to match agoric-sdk's engines range (^22.11 || ^24.14). The Yarn install step still described Yarn 1 with a corepack pin of 1.22.5, but the default dapp-offer-up template pins Yarn Berry 4.7.0; update the guide to match. Fix a bigint literal bug in the sell-concert-tickets code sample (bare `n` where `1n`/`10n` bigints are required). Retire deploying.md, which described the retired ag-solo `agoric deploy` model (home object, contract/deploy.js + api/deploy.js, REPL) that no longer matches any current dapp template; the current core-eval flow is already documented accurately in explainer-deploying-a-smart-contact.md, so redirect the old path there and fix its one inbound link plus a stale zoe.install() code sample in eventual-send.md. Fix "Smart Contact" title typo. Soften a swaparoo doc's dated "will be addressed in an upcoming release" promise about a namesByAddressAdmin bug that is still unfixed upstream. Bump one ui-tutorial dependency pin (@interchain-ui/react 1.22.11 -> 1.23.11) to match what agoric-labs/ui-tutorial's checkpoint branches actually pin. Verified against live agoric-sdk (engines, CLI defaults), the dapp-offer-up and dapp-agoric-basics template repos, and the agoric-labs/ui-tutorial checkpoint-1..5 branches: the seven ui-tutorial pages' code samples and dependency pins (@agoric/react-components, @agoric/web-components, @agoric/rpc, @agoric/store, cosmos-kit) match the actual checkpoint branches exactly, despite lagging the unreleased tip of Agoric/ui-kit, whose API has since diverged in breaking ways (AgoricProvider props, useAgoric's package). Bumping those pins to ui-kit's latest would break the tutorial rather than fix it, since agoric-labs/ui-tutorial has not itself been updated; left as-is. contract-rpc.md's mainnet1B source permalinks were also re-verified line-by-line against that tag and found accurate, contrary to the survey's suspicion of drift. yarn docs:build (including the internal link checker) passes locally. Co-Authored-By: Claude Sonnet 5 --- _redirects | 5 +- main/guides/getting-started/deploying.md | 100 ------------------ .../explainer-deploying-a-smart-contact.md | 4 +- main/guides/getting-started/index.md | 8 +- ...sell-concert-tickets-contract-explainer.md | 4 +- .../swaparoo-how-to-swap-assets-explainer.md | 2 +- .../ui-tutorial/agoric-provider.md | 2 +- main/guides/js-programming/eventual-send.md | 16 +-- 8 files changed, 22 insertions(+), 119 deletions(-) delete mode 100644 main/guides/getting-started/deploying.md diff --git a/_redirects b/_redirects index 1d99c0875..11c32f71e 100644 --- a/_redirects +++ b/_redirects @@ -36,8 +36,11 @@ /getting-started/start-a-project.html /guides/getting-started/ /getting-started/start-a-project/* /guides/getting-started/start-a-project/:splat /guides/agoric-cli/commands /guides/agoric-cli/ -/guides/agoric-cli/commands.html /guides/agoric-cli/ +/guides/agoric-cli/commands.html /guides/agoric-cli/ /guides/agoric-cli/commands/* /guides/agoric-cli/:splat +/guides/getting-started/deploying /guides/getting-started/explainer-deploying-a-smart-contact +/guides/getting-started/deploying.html /guides/getting-started/explainer-deploying-a-smart-contact +/guides/getting-started/deploying/* /guides/getting-started/explainer-deploying-a-smart-contact:splat /guides/js-programming/ses/lockdown https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/lockdown.md /guides/js-programming/ses/lockdown.html https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/lockdown.md /guides/js-programming/ses/ses-guide https://github.com/endojs/endo/blob/HEAD/packages/ses/docs/guide.md diff --git a/main/guides/getting-started/deploying.md b/main/guides/getting-started/deploying.md deleted file mode 100644 index b5a7445d8..000000000 --- a/main/guides/getting-started/deploying.md +++ /dev/null @@ -1,100 +0,0 @@ -# Deploying Smart Contracts - -The `agoric deploy` command in the [Agoric command line tool](/guides/agoric-cli/index#agoric-deploy) supports deploying contracts and off-chain web applications that talk to those contracts. The command has two primary uses: - -- Deploy smart contract source code onto the blockchain. -- Deploy and set up an application program on a local server running an Agoric process. - -Use the `agoric deploy` command to run your dapp's `contract/deploy.js` -and `api/deploy.js` scripts. You can use the deploy scripts copied from an existing -Dapp as they are, or you can modify them as suggested later in this document. - -Remember, your Dapp has three primary subdirectories: - -- `contract/` contains files defining your on-chain smart contract. -- `api/` contains files enabling the UI frontend to communicate via HTTP/WebSocket to an on-chain backend contract instance and start your Dapp contract instance and backend. -- `ui/` contains files relating to your contract's browser user interface. - -## How It Works - -All deployment happens via the local running Agoric process. This is usually the **ag-solo** process, -sometimes described as an Agoric VM or a local server. - -`ag-solo` communicates with either a locally running or remote chain. -The local process has a `home` object, which contains references to services on-chain -that can be used to call associated API commands. -Such references include `zoe`, the `board` for sharing objects, and the application user's `wallet`. - -Each `deploy.js` runs in its own temporary process connected to `ag-solo`, through which it can reach the chain. -It first uploads bundled contract source code to `ag-solo`, -then goes through the `home` object to access `zoe` and uses that to install the code on-chain. - -All on-chain commands that deployment scripts use to deploy contracts and Dapps -are also available to developers via the REPL associated with their wallet. - -## Contract Deployment - -First, let's look at _contract deployment_. `contract/deploy.js` bundles up a contract's source code -(which may consist of multiple files and modules) and "installs" -it on the blockchain as source code, using `Zoe`. -This does _not_ execute contract code; it just makes the code available on-chain. - -The contract deployment process uses [`zoe.install()`](/reference/zoe-api/zoe#e-zoe-install-bundle) -to install the contract source code on-chain. This returns an _installation_ associated with the -source code. In a typical contract deployment, the deploy script adds the installation -to the default shared board so it is broadly accessible on the chain. The script then writes -the board id to a config file in the Dapp's `ui` directory as shown below. - -By default, when you run `agoric init`, your dapp gets -the [`dapp-fungible-faucet` `contract/deploy.js` file](https://github.com/Agoric/dapp-fungible-faucet/blob/HEAD/contract/deploy.js), -which is our example of a typical contract deploy script. - -Deploying the `dapp-fungible-faucet` contract (e.g., with `agoric deploy contract/deploy.js` after `agoric init` -copied it into a local directory) installs it on chain, and generates the -file `ui/public/conf/installationConstants.js` with contents like: - -```js -// GENERATED FROM dapp-fungible-faucet/contract/deploy.js -export default { - CONTRACT_NAME: 'fungibleFaucet', - INSTALLATION_BOARD_ID: '1456154132' -}; -``` - -The board provides a unique ID per object, in this case -`"1456154132"`, so it is different for each contract deployment. - -## Application Service Deployment and Setup - -Next, let's look at _application deployment and setup_. As compared to contract deployment, -you need to customize the Agoric API server deployment and setup much more -for your particular application and contract. Some Dapps use a singleton contract instance -which presumes that it will be installed once and serve all customers (as opposed to an auction -or swap contract, which is installed once, but instantiated separately for each sale it manages). -A singleton may need to: - -- Be instantiated -- Find and connect to on-chain resources such as issuers for specific currencies -- Create new on-chain resources like new currencies or NFTs -- Create new Purses for the application to use -- Seed the on-chain contract instance with initial orders or configuration. - -These example contract `api/deploy.js` scripts show some of the -range of the above custom setup actions: - -- [`dapp-fungible-faucet`](https://github.com/Agoric/dapp-fungible-faucet/blob/HEAD/api/deploy.js) -- [`dapp-card-store`](https://github.com/Agoric/dapp-card-store/blob/HEAD/api/deploy.js) -- [`dapp-simple-exchange`](https://github.com/Agoric/dapp-simple-exchange/blob/HEAD/api/deploy.js) - -Application deployment steps may include: - -- Bundle the `api/` code and deploy it to the running local `ag-solo` -- Include the contract installation configuration information in the bundle -- Create new currencies and add them to the application's wallet - -Steps for contracts that use a singleton instance for all clients may further include: - -- Instantiate a contract instance using the installation created by contract deployment -- Use the invitation from that instance creation to configure the new instance -- Register the contract instance's `instance` with the Board -- Record the contract instance's Board ID in a configuration file diff --git a/main/guides/getting-started/explainer-deploying-a-smart-contact.md b/main/guides/getting-started/explainer-deploying-a-smart-contact.md index 223b9138c..b0f38b746 100644 --- a/main/guides/getting-started/explainer-deploying-a-smart-contact.md +++ b/main/guides/getting-started/explainer-deploying-a-smart-contact.md @@ -1,6 +1,6 @@ -# Deploying a Smart Contact +# Deploying a Smart Contract -In the `dapp-offer-up` tutorial you just went through you saw how quick and easy it was to deploy a contact on Agoric using the `yarn start:contract` command. Let's take a look at how this command works and what's going on behind the scenes. +In the `dapp-offer-up` tutorial you just went through you saw how quick and easy it was to deploy a contract on Agoric using the `yarn start:contract` command. Let's take a look at how this command works and what's going on behind the scenes. ## How it Works diff --git a/main/guides/getting-started/index.md b/main/guides/getting-started/index.md index d5291f553..b1ecdc3fa 100644 --- a/main/guides/getting-started/index.md +++ b/main/guides/getting-started/index.md @@ -89,7 +89,7 @@ source $(brew --prefix nvm)/nvm.sh Then, install Node.js. ```sh -nvm install v18.18.0 +nvm install v22.11.0 ``` Finally, verify the Node.js version. @@ -102,17 +102,17 @@ node --version ### Installing Yarn -This will install yarn, and verify it is installed correctly. Install yarn by either running `npm install --global yarn`, or visit https://classic.yarnpkg.com/en/docs/install for more information. See below, `corepack enable` will add the Corepack shims to the install directories, and `yarn --version` will verify yarn is installed correctly. +This will install yarn, and verify it is installed correctly. `corepack enable` will add the Corepack shims to the install directories, and `yarn --version` will verify yarn is installed correctly. ```sh corepack enable yarn --version # for verification ``` -This app uses Yarn 1, so running the above command will show a version in the format `1.x.x`. If you are using a different version of `yarn`, you can use `yarn set version ` to switch like in the example below. +The sample dapp pins Yarn Berry (`"packageManager": "yarn@4.7.0"` in its `package.json`), so once you're inside the `demo` directory (see [Creating Your Dapp From a Template](#creating-your-dapp-from-a-template) below), Corepack will pick up that version automatically. If it does not, you can set it explicitly: ```sh -yarn set version 1.22.5 +yarn set version 4.7.0 ``` ### Installing Docker diff --git a/main/guides/getting-started/sell-concert-tickets-contract-explainer.md b/main/guides/getting-started/sell-concert-tickets-contract-explainer.md index 407a36f71..4f23a14df 100644 --- a/main/guides/getting-started/sell-concert-tickets-contract-explainer.md +++ b/main/guides/getting-started/sell-concert-tickets-contract-explainer.md @@ -30,8 +30,8 @@ const inventory = { maxTickets: 5n }, backRow: { - tradePrice: AmountMath.make(istBrand, n), - maxTickets: n + tradePrice: AmountMath.make(istBrand, 1n), + maxTickets: 10n } }; ``` diff --git a/main/guides/getting-started/swaparoo-how-to-swap-assets-explainer.md b/main/guides/getting-started/swaparoo-how-to-swap-assets-explainer.md index df3a18429..84bd946cf 100644 --- a/main/guides/getting-started/swaparoo-how-to-swap-assets-explainer.md +++ b/main/guides/getting-started/swaparoo-how-to-swap-assets-explainer.md @@ -2,7 +2,7 @@ This smart contract is designed to allow two parties to swap assets between themselves, with a fee charged to one of the parties. The contract is started with a `feeAmount` and a `namesByAddressAdmin` object, which is used to retrieve a deposit facet for the second party. -**NOTE:** _`namesByAddressAdmin` is actually excess authority in this scenario. Normally read-only access can be attained via `namesByAddress`. The use of `namesByAddressAdmin` in this example is due to a bug, which will be addressed in an upcoming release._ +**NOTE:** _`namesByAddressAdmin` is actually excess authority in this scenario. Normally read-only access can be attained via `namesByAddress`. The use of `namesByAddressAdmin` in this example is due to a bug that has not yet been fixed upstream; treat it as a known rough edge rather than something a template consumer needs to work around._ Let's take a look at how this contract works: diff --git a/main/guides/getting-started/ui-tutorial/agoric-provider.md b/main/guides/getting-started/ui-tutorial/agoric-provider.md index 67ba73764..5a878d612 100644 --- a/main/guides/getting-started/ui-tutorial/agoric-provider.md +++ b/main/guides/getting-started/ui-tutorial/agoric-provider.md @@ -14,7 +14,7 @@ This makes it easy to handle all the platform-specific implementation details, s Install the following dependencies: ``` -yarn add -D @agoric/react-components@0.2.0 cosmos-kit@2.8.5 @interchain-ui/react@1.22.11 +yarn add -D @agoric/react-components@0.2.0 cosmos-kit@2.8.5 @interchain-ui/react@1.23.11 ``` The `cosmos-kit` dependency is used to provide different wallets in the wallet connection modal. diff --git a/main/guides/js-programming/eventual-send.md b/main/guides/js-programming/eventual-send.md index de965f27a..9c8f8ba9a 100644 --- a/main/guides/js-programming/eventual-send.md +++ b/main/guides/js-programming/eventual-send.md @@ -7,18 +7,18 @@ In web browsers, a common pattern of remote communication is using the In the Agoric platform, communicating with remote objects is similar, using the `E()` wrapper. For example, -a [deploy script](../getting-started/deploying) may want to use the -[Zoe Service API](/reference/zoe-api/zoe) to install a contract on a blockchain. -But the deploy script cannot call `zoe.install(bundle)`, because it does not have local -access to the `zoe` object. However, the deploy -script is given a `zoe` _remote presence_. To call methods on the -actual Zoe object, the deploy script can do: +a [core-eval script](../getting-started/explainer-deploying-a-smart-contact) may want to use the +[Zoe Service API](/reference/zoe-api/zoe) to install a contract on the chain. +But the script cannot call `zoe.installBundleID(bundleId)` directly, because it does not have local +access to the `zoe` object. However, the script +is given a `zoe` _remote presence_ among its permitted powers. To call methods on the +actual Zoe object, the script can do: ```js import { E } from '@endo/eventual-send'; -E(zoe).install(bundle) - .then(installationHandle => { ... }) +E(zoe).installBundleID(bundleId) + .then(installation => { ... }) .catch(err => { ... }); ```