Skip to content

Commit

Permalink
docs: use yarn start:contract; add screenshots etc.
Browse files Browse the repository at this point in the history
  • Loading branch information
@dckc
dckc committed Dec 6, 2023
1 parent 18aa19b commit 737bdd3
Showing 1 changed file with 127 additions and 59 deletions.
186 changes: 127 additions & 59 deletions main/guides/getting-started/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
# Starting a Basic Dapp

Welcome! We'll start with a basic _dapp_; that is: a JavaScript contract and UI.
Welcome! We'll start with a basic _dapp_; that is: a JavaScript contract and associated UI.

<img alt="Vite + React + Agoric page with Connect Wallet button"
style="border: 1px solid" width="300"
src="https://github.com/Agoric/documentation/assets/150986/36a87384-0148-4f9e-8606-e176bd7880b3" />

```js
/** @param {ZCF<{joinPrice: Amount}>} zcf */
export const start = async zcf => {
const { joinPrice } = zcf.getTerms();
...
}
```

But first, note that help is not far away:
As we begin, note that help is not far away:

## Getting Support

Expand All @@ -12,6 +24,13 @@ But first, note that help is not far away:

## Platform Requirements

The Agoric SDK is supported on <a href="https://en.wikipedia.org/wiki/Linux">Linux</a>, <a href="https://www.apple.com/macos/">MacOS</a>, and <a href="https://docs.microsoft.com/en-us/windows/wsl/">Windows Subsystem for Linux (WSL)</a>.

::: tip Mac Dev Tools
On a Mac, be sure to install
[Xcode](https://apps.apple.com/us/app/xcode/id497799835).
:::

We support any long-term support (LTS) versions of Node.js.
Download and install from [Node.js](https://nodejs.org/) if you don't
already have `node`. Check to make sure:
Expand All @@ -27,16 +46,10 @@ corepack enable
yarn --version # 1.x
```

The Agoric SDK is supported on <a href="https://en.wikipedia.org/wiki/Linux">Linux</a>, <a href="https://www.apple.com/macos/">MacOS</a>, and <a href="https://docs.microsoft.com/en-us/windows/wsl/">Windows Subsystem for Linux (WSL)</a>.

::: tip Mac Dev Tools
On a Mac, you must first install
[Xcode](https://apps.apple.com/us/app/xcode/id497799835)
:::

We support running a local Agoric blockchain with [docker-compose](https://docs.docker.com/compose/).
For this getting started exercise, you will need:

Our user interfaces integrate with the [keplr](https://www.keplr.app/) wallet.
- [docker compose](https://docs.docker.com/compose/)
- [Keplr wallet](https://www.keplr.app/) wallet.

## Create a project with the basic starter kit

Expand Down Expand Up @@ -77,9 +90,8 @@ Disregard these contents, for now:

- **\_agstate**
- **api**
:::

node_modules
:::

## Install dependencies

Expand Down Expand Up @@ -116,84 +128,140 @@ The fist time you pull it may take several minutes.

:::

Look at the logs from the blockchain until it is steadily making blocks:
Look at the logs from the blockchain:

```sh
yarn docker:logs
```

## Deploy the Contract and Start the UI

Let's start it up:
After an initial flurry, when it is steadily making blocks, you should see:

```sh
yarn start
```
agd_1 | 2023-12-05T20:52:42.933Z block-manager: block 956 begin
agd_1 | 2023-12-05T20:52:42.936Z block-manager: block 956 commit
agd_1 | 2023-12-05T20:52:43.944Z block-manager: block 957 begin
agd_1 | 2023-12-05T20:52:43.946Z block-manager: block 957 commit
```

::: tip TODO: integrated `yarn start` script
Use control-C to stop viewing the logs and return to a shell prompt.

For now, use the [Agoric Gov Proposal Builder](https://cosgov.org/)
for deployment:
::: tip Note: logs include benign error messages

1. Make the contract and proposal bundles.
You can disregard messages such as:

```sh
(cd contract; yarn build:proposal)
```
- `v5: TypeError: target has no method "getDisplayInfo"`

Note the long `b1-xxx.json` bundle filenames
as well as `start-game1-permit.json`
and `start-game1.js`.
These are artifacts of replaying historical events.

2. Use the [Install Bundle](https://cosgov.org/?msgType=installBundle&network=local) tab to install the 2 bundles.
It will likely say **insufficient balance**.
To get enough IST:
:::

```sh
yarn docker:make mint4k
```
## Deploy the Contract

2. Get ready to vote. To query the status of proposals, use
Let's deploy the contract:

```sh
yarn docker:make gov-q
yarn start:contract
```

Then, don't execute this command, but get it ready:
This `start:contract` script will do a number of things that we will cover in more detail later:

```sh
yarn docker:make vote PROPOSAL=N
```
1. Bundle the contract with `agoric run ...`
2. Collect some ATOM with `agd tx bank send ...`.
3. Use the ATOM to open a vault to mint enough IST to pay to install the bundles on chain with `agops vaults open ...`.
4. Install the bundles on chain with `agd tx swingset install-bundle ...`.
5. Collect enough BLD to pay for a governance deposit with `agd tx bank send ...`
6. Make a governance proposal to start the contract with `agd tx gov submit-proposal swingset-core-eval ...`.
7. Vote for the proposal; wait for it to pass.
8. Print key material for an account you can use.

3. Use the [CoreEval Proposal](https://cosgov.org/?msgType=coreEvalProposal&network=local) tab to make a proposal to
start the contract using the permit and script.
Note the **10 second voting period**,
When you **Sign & Submit** the proposal, you can replace `N`
above with the proposal number that pops up.
## Set up Keplr wallet and import account

To verify that the proposal executed correctly:
Install the [Keplr Wallet](https://www.keplr.app/) if you have not done so already. Then copy the _mnemonic phrase_ printed at the end of the previous step; for example copy `congress` thru `switch` in the following:

```sh
docker-compose logs | less -R
```
Import the following mnemonic into Keplr:
congress goose visual acid shine view pair fruit chaos boost cigar upgrade certain warrior color omit perfect clutch little bulb divorce split fashion switch
The resulting address should be: agoric1a3zu5aqw255q0tuxzy9aftvgheekw2wedz3xwq
```

::: tip Keep your own mnemonic confidential!

For any mnemonic phrase you use to secure your own assets, **take care to keep it strictly confidential!** The mnemonic here is only for testing.
Using a **separate browser profile** is a good way to avoid accidentally
using the wrong account when testing vs. with real assets.

The logs should include some `console.log` output with no errors.
:::

Import it into Keplr:

1. Inside your Keplr wallet browser extension, press the ‘Accounts’ icon on the top right corner and then click the ‘Add Wallet button.

<img width="800" src="https://assets-global.website-files.com/634f88fecbcc16e1f71b7e3c/635b7493ae1431bd476ce90e_Adding%20Accs.png" />

2. Choose **Import an existing wallet**.

3. Choose **Use recover phrase or private key**.

4. Paste the mnemonic. Hit **Import**.

**TODO: what console output exactly?**
<img width="800" src="https://assets-global.website-files.com/634f88fecbcc16e1f71b7e3c/6363571c7c3d77a25e1d9bbf_accs7.webp" />

5. Enter a **Wallet Name** such as `user1`. Hit **Next**.

6. On the **Select Chains** page, hit **Save** (_choice of chain does not matter at this point._)

::: tip See also Keplr docs

The figures above are from...

- [Connect Additional Keplr Accounts](https://help.keplr.app/articles/how-to-connect-additional-keplr-accounts)
- [Four Ways to Create a Keplr Account](https://help.keplr.app/articles/four-ways-to-create-a-keplr-account#:~:text=Import%20an%20Existing%20Account%20via%20Mnemonic%20Phrase)

:::

4. Start the UI
**Import an Existing Account via Mnemonic Phrase** in
[Four Ways to Create a Keplr Account](https://help.keplr.app/articles/four-ways-to-create-a-keplr-account#:~:text=Import%20an%20Existing%20Account%20via%20Mnemonic%20Phrase)

## Start the Dapp UI

To start the Dapp UI:

```sh
(cd ui; yarn dev)
yarn start:ui
```

:::
The result includes a link:

```
VITE v4.5.0 ready in 132 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h to show help
```

Use `yarn docker:bash` to print account info, including `user1`.
Add that account to keplr using its mnemonic.
Follow that link to get the Dapp UI:

Then hit **Connect Wallet**. The UI should show your address.
<img alt="Vite + React + Agoric page with Connect Wallet button"
style="border: 1px solid"
src="https://github.com/Agoric/documentation/assets/150986/36a87384-0148-4f9e-8606-e176bd7880b3" />

Then hit **Connect Wallet**. The UI should show your address and your IST balance, after you approve an **Add Agoric local to Keplr** dialog.

## Make an Offer

Then hit **Make Offer**. Keplr should show an offer to **give** 0.25 IST
and **want** a few places. Approve the offer to sign and broadcast it to the (local) blockchain.

<img alt="Confirm Transaction with Give / Want offer details"
style="border: 1px solid"
src="https://github.com/Agoric/documentation/assets/150986/fd724782-9480-4acf-8e10-e0da5c780248" />

Then **Make Offer**. Keplr should show an offer to **give** 0.25 IST
and **want** a few places. Sign and broadcast the offer.
After a few seconds, the UI should show the places.

<img alt="Purses display updated with wanted Places"
style="border: 1px solid"
src="https://github.com/Agoric/documentation/assets/150986/64c0fe24-8238-4839-add8-5c1007722756" />

Congratulations! You are on your way to building on Dapps on Agoric.

0 comments on commit 737bdd3

Please sign in to comment.