Skip to content

tutorial.md

Latest commit

 

History

History
336 lines (232 loc) · 13.7 KB

tutorial.md

File metadata and controls

336 lines (232 loc) · 13.7 KB
Raw

SimpleExchange dApp tutorial

Description

This tutorial showcases how to interact with the SimpleExchange dApp in a local environment, as well as how to deploy the contract in the Agoric Devnet.

The tutorial page is structured as follows:

  • Pre-requisites
  • Contract Testing
    • Unit tests
    • Integration tests
    • Smoke tests
    • Swingset tests
  • Contract Deployment
  • Launch UI

Prerequisites

  • Follow the installing the Agoric SDK guide to install the Agoric Software Development Kit (SDK);
    • Important: instead of using the community-dev branch, you need to check out the following revision: 92b6cd72484079b0349d8ccfa4510aeb820e8d67, which is the one used on Devnet at the moment that this component was developed.
go version # go version go1.20.6 darwin/arm64
node --version # v18.18.0
npm --version # 9.8.1
yarn --version # 1.22.5

# inside agoric-sdk folder
`git checkout 92b6cd72484079b0349d8ccfa4510aeb820e8d67`
yarn install && yarn build
agoric --version # 0.21.2-u11.0
cd simple-exchange/contract
agoric install

Contract Testing

Unit tests

We covered the most important cases in unit tests, making sure that the exchange contract works as expected. The testing framework used is Ava, and we build a set of tools that make the testing environment cleaner and easier to scale.

We include 2 versions of unit tests, one for the basic and the other for the upgradable version of the contract. Both of them contain the exact same test cases, but each of them reflects the difference when deploying, configuring, and communicating with the durable and non-durable contract versions :

  • ./contract/test/unitTests/test-simpleExchange.js
  • ./contract/test/unitTests/test-upgradableSimpleExchange.js

Unit tests include the following test cases:

  • make sell offer - check that the contract properly handles incoming sell offer
  • make buy offer - check that the contract properly handles incoming buy offer
  • make trade - check that the contract properly executes the exchange when sell and buy offers can satisfy each other
  • make offer with wrong issuers - check that offer with the wrong issuer fails
  • make offer with offerProposal missing attribute - check that offer with wrong offerProposal attributes fails
  • make offer without offerProposal - check that offer without offerProposal fails
  • offers with null or invalid shapes on the proposals - check with different invalid shapes set that each of them fails
  • make offer with NFT - check that NFTs can be traded on the exchange properly
  • make offer with misplaced issuers - check if the contract refuses an order with a mismatch in the keyword-issuer pair
  • make trade with surplus assets in Alice's payout - check if the contract returns the expected surplus when an exchange is done

To run unit tests, just run the following command:

cd simple-exchange/contract
yarn unit-test-basic
yarn unit-test-upgradable

This will run all test cases in each file. You will see a lot of debug console logs from Agoric SDK, including some errors - these errors are triggered by unit tests to assert the failing branches. In total 16 unit tests should pass, 8 tests for basic contract and 8 tests for durable contract.

Integration tests

The integration test is setting up a testing environment with 2 different smart wallets and checks that simpleExchange contract can execute a successful exchange. In order to run unit tests, follow these instructions and then run this command:

cd simple-exchange/contract
yarn integration-test

Swingset tests

The swingset tests are meant to check that simpleExchange contract upgradeability works as expected. In this case, it means that the orderBook state and the subscriber object survive a contract upgrade.

The swingset test includes 3 test cases:

  • null-upgrade - check that the contract null-upgrade is executed successfully
  • null-upgrade-orderBook - check that the upgrade is executed successfully and the order book is preserved
  • null-upgrade-exchange - check that the contract can execute a match an order made before the upgrade with one made after it.

To run Swingset tests, just run the following command:

cd simple-exchange/contract
yarn swingset-test

Smoke tests

The smoke tests intend to build the core-eval and deploy the simpleExchange contract in a local chain, and interact with it using shell scripts.

Create gov1 and gov2 keys

Open a new terminal and run these commands:

agd keys add gov1 --keyring-backend=test
agd keys add gov2 --keyring-backend=test

Note: save the mnemonic phrase printed in the terminal in a safe place. They will be useful if you wish import this account to the Keplr wallet.

Launch local chain and client

In the same terminal as above run these commands:

cd agoric-sdk/packages/inter-protocol/scripts
./start-local-chain.sh

If you get the following error message FATAL ERROR: listen EADDRINUSE: address already in use :::9464, stop the process and execute the following commands:

lsof -i :9464
kill <PID>

In a second terminal run these commands:

cd agoric-sdk/packages/cosmic-swingset
make SOLO_COINS='13000000ubld,12345000000000uist,1122000000ibc/toyusdc' scenario2-run-client

Submit core-eval

For this section, the first step is to make sure that the SDK_ROOT path, in the Makefile is pointing to your agoric-sdk.
If so, open a third terminal and run these commands:

cd simple-exchange/contract
make bundle-contract

Note: your terminal will print a message similar to the one below, make sure to copy the bundle IDs (b1-265...e54.json and b1-60f...509.json) and update the Makefile variables CONTRACT_REF_BUNDLE_ID and MANIFEST_REF_BUNDLE_ID respectively.

...
Remember to install bundles before submitting the proposal:
  agd tx swingset install-bundle @/Users/jorgelopes/Documents/GitHub/Agoric/bytepitch-bounties/simple-exchange/contract/cache/b1-180be6a3be174c957d853e862801c3643a2897ef3e96993507fe6a02ad57d33806754bf2bc73bb2664f8536861e42d46139971f9cc85724abed9408ba1b57e8a.json
  agd tx swingset install-bundle @/Users/jorgelopes/Documents/GitHub/Agoric/bytepitch-bounties/simple-exchange/contract/cache/b1-b2bb6209e466d1d7298523776513ce11c57c2eef47e52e050b5f40c2e056a03ae350c2328ad05b748ae8ee503e94c4b9ebf974aea3202643d0c7377bbe582aea.json

After making the adjustments mentioned above, run the following command in the same terminal:

make submit-core-eval

Now you should see the success message in the chain logs, and also, be able to query the contract instance in the agoricNames. Note that if you plan to execute this command more than once, you need to overwrite the variable VOTE_PROPOSAL accordingly.

Run smoke tests

Before executing the offer scripts, it is necessary to update the assets and reference lists with the respective board IDs, for that run the following commands:

cd simple-exchange/contract/test/smokeTests/
agoric deploy updateAssetList
agoric deploy updateReferenceList

After completing the process above, you can now make sell and buy orders by running each of the following scripts:

cd simple-exchange/contract/test/smokeTests/
./sellOffer.sh
./buyOffer.sh

Verify order book

There are 2 methods to easily query the contract state of the order book:

  1. Agoric Wallet REPL
    • get instance from agoricNames
    • get publicFacet
    • get subscriber
    • get updated state

REPL commands

  1. Storage Viewer
    • load published children's keys
    • load simpleExchange data

Contract Deployment

This chapter contains code and instructions for submitting a swingset.CoreEval proposal to add the simpleExchange dApp to the Agoric Devnet.

The build the core-eval it was required to first prepare the simpleExchange-proposal and proposalBuilder-script. A Makefile was also built to facilitate the process of deploying the contract.

Bundle the contract

Open a new terminal and run the following commands:

cd simple-exchange/contract
make bundle-contract

This target will generate the startSimpleExchange and startSimpleExchange-permit files in the project root, as well as the contract and manifest bundles.

Note: your terminal will print a message similar to the one below, make sure to copy the bundle IDs (b1-265...e54.json and b1-60f...509.json) and update the Makefile variables CONTRACT_REF_BUNDLE_ID and MANIFEST_REF_BUNDLE_ID respectively.
See Smoke tests for more details

Setup wallet

One wallet is needed for submitting the proposal, for that you can run the following command on the terminal:

agd keys add gov

Set up a smart-wallet and request funds at the devnet faucet, using the address from the previous step.

Install bundles

To install the bundles follow these instructions in the same terminal as above

make install-bundles-dev

Verify the bundle deployment by running the following command:

agd query vstorage data bundles --node='https://devnet.rpc.agoric.net:443' --chain-id='agoricdev-23'

Submit proposal

The next step is to submit the proposal, to do that run the following command:

make submit-proposal-dev

Verify that the proposal was submitted by running the following command:

agd query gov proposals --node='https://devnet.rpc.agoric.net:443' --chain-id='agoricdev-23' --output json | jq -c '.proposals[] | [.proposal_id,.voting_end_time,.status]';

You can also follow the state of your proposal on the Agoric devnet explorer.

Get the proposal approved

To deploy a contract on devnet, the proposal needs to pass the voting stage. So it is advised to inform the community on the devnet channel on Agoric discord in advance, that you plan to submit a proposal, so they can vote on it.

Useful source of information

Launch UI

To launch the simpleExhanghe UI the first step is to update the RPC address and chain ID according to where the contract was deployed. At the store.js file, line 5, update the rpcAddr and chainId passed to the makeAgoricChainStorageWatcher.

If you wish to run the application on:

  • local chain - ('http://localhost:26657', 'agoriclocal')
  • devnet - ('https://devnet.rpc.agoric.net:443', 'agoricdev-23')

Then, open a new terminal and run the following commands:

cd simple-exchange/ui
yarn
yarn run dev

Now, you can open your browser and go to http://localhost:5173/#trade

Multiple Users Test with Keplr Wallet Extension

In this guide, we'll demonstrate how to test multi-user functionality using a wallet extension like Keplr. We'll use two different users, Bob and Emma, to show how transactions and orders appear for separate accounts.

Requirements

  • Keplr wallet extension installed in your browser.
  • Access to a local server (http://localhost:5173/#trade).
  • Two sets of government keys for wallet setup.

Steps

Setting Up the First User (Bob)
  1. Open a new browser or a new user profile.
  2. Open the Keplr wallet extension.
  3. Click on 'Import existing wallet'.
  4. Choose 'Use Recovery Phrase or Private Key'.
  5. Select the '24 words' option and insert the first government key (gov1).
  6. Navigate to http://localhost:5173/#trade and connect to the wallet.
Creating a Sell Order as Bob
  1. Place a sell order, e.g., sell 0.002 BLD for 0.001 IST.
  2. If the transaction is successful, check the 'Order Book' and 'Your Orders' tab to see your order.
Setting Up the Second User (Emma)
  1. Open a new browser or user profile different from Bob's.
  2. Follow the same steps to set up the wallet, but use the second government key (gov2).
  3. Connect to http://localhost:5173/#trade with the new wallet.
Viewing Bob's Sell Order as Emma
  1. As Emma, you will see Bob's sell order in the 'Order Book'.
  2. However, it won't appear in Emma's 'Your Orders' tab as it belongs to Bob.
Creating a Sell Order as Emma
  1. Place a sell order, like 0.001 BLD for 0.03 IST.
  2. Upon successful transaction, this order will appear in both the 'Order Book' and Emma's 'Your Orders' tab.
Matching Orders Between Users
  1. As Bob, create a buy order matching Emma's sell order, for instance, 0.03 IST for 0.001 BLD.
  2. If the orders match, they will disappear from the 'Order Book'.
  3. The matched order will no longer be visible in either user's 'Your Orders' tab.

Conclusion

Through these steps, you can simulate a trading scenario with two different users. This demonstrates how orders are specific to each user's wallet and how matched orders are processed and removed from the system.