From f4887f5e90e1ea3ffcc3e3e3043128db5010b57e Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Tue, 26 Mar 2024 08:02:34 -0600 Subject: [PATCH 1/3] Created how-to-use-ui-kit explainer Explainer for getting started with `ui-kit` --- .../getting-started/how-to-use-ui-kit.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 main/guides/getting-started/how-to-use-ui-kit.md diff --git a/main/guides/getting-started/how-to-use-ui-kit.md b/main/guides/getting-started/how-to-use-ui-kit.md new file mode 100644 index 000000000..ada70a914 --- /dev/null +++ b/main/guides/getting-started/how-to-use-ui-kit.md @@ -0,0 +1,147 @@ +# Introduction to Agoric UI Kit +The Agoric UI Kit is a collection of components and tools designed to help developers build graphical user interfaces for Agoric decentralized applications (dapps). It provides a set of reusable React components, utilities for reading contract data from vstorage, functions for connecting to the user's wallet, and methods for executing offers on the Agoric blockchain. + +## Setup +To use the Agoric UI Kit, you need to set up SES (Secure ECMAScript) in your application environment. SES is a secure runtime for JavaScript that ensures the security and integrity of your Agoric dapp. Refer to the [SES setup example](https://github.com/Agoric/dapp-inter/blob/main/src/main.tsx#L1) for instructions on enabling SES in your application. + +## React Components +The UI Kit provides a set of React components in the `packages/react-components` directory. These components are designed to make it easier to build user interfaces for Agoric dapps using React. To use these components, simply import them into your React application and integrate them into your UI. + +## Reading Contract Data (vstorage) +The UI Kit includes utilities for reading data from vstorage, the virtual storage system used by Agoric contracts. The `makeAgoricChainStorageWatcher` function allows you to subscribe to updates to vstorage and efficiently retrieve data using the Agoric RPC API. + +```js +import { + makeAgoricChainStorageWatcher, + AgoricChainStoragePathKind as Kind, +} from '@agoric/rpc'; + +const watcher = makeAgoricChainStorageWatcher(restApi, chainName); + +// Watch vstorage children at a given node. +const stopWatching = watcher.watchLatest( + [Kind.Children, 'published.vaultFactory.managers'], + managerIds => { + console.log('Got vault manager IDs:', managerIds); + }, +); + +// Stop watching. +stopWatching(); + +// Watch vstorage data at a given node. +watcher.watchLatest( + [Kind.Data, 'published.agoricNames.brand'], + brands => { + console.log('Do something with the brands'); + }, +); +``` + +### Connecting to User's Account (Keplr) +The UI Kit provides the `makeAgoricWalletConnection` function to connect to the user's wallet using Keplr, a browser extension for interacting with Agoric and Cosmos-based blockchains. This function allows you to retrieve information about the user's purses (token accounts) and other account-related data. + +```js +import { subscribeLatest } from '@agoric/notifier'; +import { makeAgoricChainStorageWatcher } from '@agoric/rpc'; +import { makeAgoricWalletConnection } from '@agoric/web-components'; + +const watcher = makeAgoricChainStorageWatcher(apiAddr, chainName); +const connection = await makeAgoricWalletConnection(watcher, rpcAddr); +const { pursesNotifier, publicSubscribersNotifier } = chainConnection; + +for await (const purses of subscribeLatest(pursesNotifier)) { + console.log('Got purses:', purses); +} +``` + +### Using a Custom Signer +If you're using a custom signer instead of Keplr, you can provide your own signer implementation when creating the `AgoricWalletConnection`. Here's an example of setting up a custom signer using the `@cosmjs/stargate` library: + +```js +import { + agoricRegistryTypes, + agoricConverters, + makeAgoricWalletConnection, +} from '@agoric/web-components'; +import { Registry } from '@cosmjs/proto-signing'; +import { + AminoTypes, + defaultRegistryTypes, + createBankAminoConverters, + createAuthzAminoConverters, +} from '@cosmjs/stargate'; + +// ... + +const signingStargateClient = await SigningStargateClient.connectWithSigner( + rpcEndpoint, // RPC endpoint to use + customAminoSigner, // E.g. window.getOfflineSignerOnlyAmino(chainId) + { + aminoTypes: new AminoTypes({ + ...agoricConverters, + ...createBankAminoConverters(), + ...createAuthzAminoConverters(), + }), + registry: new Registry([...defaultRegistryTypes, ...agoricRegistryTypes]), + }, +); +const agoricWalletConnection = await makeAgoricWalletConnection( + chainStorageWatcher, + rpcEndpoint, + (e: unknown) => { + console.error('wallet connection error', e); + }, + { address: myAddress, client: signingStargateClient }, +); +``` + +## Executing Offers +The UI Kit provides functionality to execute offers (transactions) on the Agoric blockchain. The `makeOffer` function allows you to create and submit an offer, specifying the contract instance, the amounts to give and want, and any additional arguments. You can also provide a callback function to handle the different stages of the offer execution process. + +```js +import { makeAgoricChainStorageWatcher } from '@agoric/rpc'; +import { makeAgoricWalletConnection } from '@agoric/web-components'; + +const watcher = makeAgoricChainStorageWatcher(apiAddr, chainName); +const connection = await makeAgoricWalletConnection(watcher, rpcAddr); + +const amountToGive = { brand: someBrand, value: 123n }; +const amountToWant = { brand: someOtherBrand, value: 456n }; + +connection.makeOffer( + { + source: 'agoricContract', + instancePath: ['SimpleSwapExampleInstance'], + callPipe: [ + ['getSwapManagerForBrand', [amountToGive.brand]], + ['makeSwapOffer'], + ], + }, + { + give: { In: amountToGive }, + want: { Out: amountToWant }, + }, + { exampleArg: 'foo' }, + ({ status, data }) => { + if (status === 'error') { + console.error('Offer error', data); + } + if (status === 'seated') { + console.log('Transaction submitted:', data.txn); + console.log('Offer id:', data.offerId); + } + if (status === 'refunded') { + console.log('Offer refunded'); + } + if (status === 'accepted') { + console.log('Offer accepted'); + } + }, +); +``` + +## Conclusion +The Agoric UI Kit provides a valuable set of tools and components for building user interfaces for Agoric dapps. By leveraging the UI Kit, developers can quickly and easily integrate React components, read contract data from vstorage, connect to the user's wallet, and execute offers on the Agoric blockchain. + +To get started with the Agoric UI Kit, make sure to set up SES correctly, follow the documentation and examples provided in the repository, and explore the various features and utilities offered by the UI Kit. From a6b1641d44632090ade60cf3531c1c23dde27351 Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Tue, 26 Mar 2024 10:20:45 -0600 Subject: [PATCH 2/3] Update how-to-use-ui-kit.md --- main/guides/getting-started/how-to-use-ui-kit.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/main/guides/getting-started/how-to-use-ui-kit.md b/main/guides/getting-started/how-to-use-ui-kit.md index ada70a914..795793ebf 100644 --- a/main/guides/getting-started/how-to-use-ui-kit.md +++ b/main/guides/getting-started/how-to-use-ui-kit.md @@ -2,7 +2,7 @@ The Agoric UI Kit is a collection of components and tools designed to help developers build graphical user interfaces for Agoric decentralized applications (dapps). It provides a set of reusable React components, utilities for reading contract data from vstorage, functions for connecting to the user's wallet, and methods for executing offers on the Agoric blockchain. ## Setup -To use the Agoric UI Kit, you need to set up SES (Secure ECMAScript) in your application environment. SES is a secure runtime for JavaScript that ensures the security and integrity of your Agoric dapp. Refer to the [SES setup example](https://github.com/Agoric/dapp-inter/blob/main/src/main.tsx#L1) for instructions on enabling SES in your application. +To use the Agoric UI Kit, you need to set up SES in your application environment. SES is a runtime for JavaScript that ensures the security and integrity of your Agoric dapp. Refer to the [SES setup example](https://github.com/Agoric/dapp-inter/blob/main/src/main.tsx#L1) for instructions on enabling SES in your application. ## React Components The UI Kit provides a set of React components in the `packages/react-components` directory. These components are designed to make it easier to build user interfaces for Agoric dapps using React. To use these components, simply import them into your React application and integrate them into your UI. @@ -140,8 +140,3 @@ connection.makeOffer( }, ); ``` - -## Conclusion -The Agoric UI Kit provides a valuable set of tools and components for building user interfaces for Agoric dapps. By leveraging the UI Kit, developers can quickly and easily integrate React components, read contract data from vstorage, connect to the user's wallet, and execute offers on the Agoric blockchain. - -To get started with the Agoric UI Kit, make sure to set up SES correctly, follow the documentation and examples provided in the repository, and explore the various features and utilities offered by the UI Kit. From 2cc6961b94018015ea2a77e1eeb8debc503342ab Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Fri, 29 Mar 2024 06:42:29 -0600 Subject: [PATCH 3/3] Update how-to-use-ui-kit.md --- main/guides/getting-started/how-to-use-ui-kit.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/main/guides/getting-started/how-to-use-ui-kit.md b/main/guides/getting-started/how-to-use-ui-kit.md index 795793ebf..aebb19c9d 100644 --- a/main/guides/getting-started/how-to-use-ui-kit.md +++ b/main/guides/getting-started/how-to-use-ui-kit.md @@ -2,7 +2,7 @@ The Agoric UI Kit is a collection of components and tools designed to help developers build graphical user interfaces for Agoric decentralized applications (dapps). It provides a set of reusable React components, utilities for reading contract data from vstorage, functions for connecting to the user's wallet, and methods for executing offers on the Agoric blockchain. ## Setup -To use the Agoric UI Kit, you need to set up SES in your application environment. SES is a runtime for JavaScript that ensures the security and integrity of your Agoric dapp. Refer to the [SES setup example](https://github.com/Agoric/dapp-inter/blob/main/src/main.tsx#L1) for instructions on enabling SES in your application. +To use the Agoric UI Kit, please follow the [instructions documented in the `ui-kit` repository](https://github.com/Agoric/ui-kit/blob/main/packages/react-components/README.md). ## React Components The UI Kit provides a set of React components in the `packages/react-components` directory. These components are designed to make it easier to build user interfaces for Agoric dapps using React. To use these components, simply import them into your React application and integrate them into your UI. @@ -39,8 +39,7 @@ watcher.watchLatest( ``` ### Connecting to User's Account (Keplr) -The UI Kit provides the `makeAgoricWalletConnection` function to connect to the user's wallet using Keplr, a browser extension for interacting with Agoric and Cosmos-based blockchains. This function allows you to retrieve information about the user's purses (token accounts) and other account-related data. - +The UI Kit provides the `makeAgoricWalletConnection` function to connect to the user's wallet using Keplr, a browser extension for interacting with Agoric and Cosmos-based blockchains. This function allows you to retrieve information about the user's purses (token accounts) and other account-related data. Please note, if you are using React, you can use `@agoric/react-components` instead of this API. ```js import { subscribeLatest } from '@agoric/notifier'; import { makeAgoricChainStorageWatcher } from '@agoric/rpc';