Skip to content

Commit 6eca109

Browse files
dckcdckc
committed
docs: Using agd to make queries and transactions
 - tip: Formatting with jq
1 parent 12b341b commit 6eca109

File tree

2 files changed

+192
-1
lines changed

2 files changed

+192
-1
lines changed

‎main/.vuepress/config.js

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,10 @@ module.exports = {
179179
title: 'Agoric CLI',
180180
path: '/guides/agoric-cli/',
181181
collapsible: false,
182-
children: ['/guides/agoric-cli/'],
182+
children: [
183+
'/guides/agoric-cli/',
184+
'/guides/agoric-cli/agd-query-tx.html',
185+
],
183186
},
184187
{
185188
title: 'JavaScript Framework',

‎main/guides/agoric-cli/agd-query-tx.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Using `agd` to make queries and transactions
2+
3+
`agd` is the Agoric Cosmos App, analagous to `simd` in the [Cosmos SDK](https://docs.cosmos.network/) simapp or `gaiad` in
4+
the Cosmos hub. Most of the `simd` [query commands](https://docs.cosmos.network/v0.46/core/cli.html#query-commands) and [transaction commands](https://docs.cosmos.network/v0.46/core/cli.html#transaction-commands) work similarly in `agd`.
5+
6+
::: tip agd for Building Dapps
7+
8+
This section focusses on commands relevant to developing and deploying smart contracts and dapps. See also:
9+
10+
- [Validators topics \- Agoric Community Forum](https://community.agoric.com/c/validators/9)
11+
- [Governance topics \- Agoric Community Forum](https://community.agoric.com/c/governance/6)
12+
- [Delegator Guide \(CLI\) \| Cosmos Hub](https://hub.cosmos.network/main/delegators/delegator-guide-cli.html)
13+
14+
:::
15+
16+
::: tip Installing agd
17+
18+
Options include:
19+
20+
- Use the [basic dapp local chain](../getting-started/#starting-a-local-agoric-blockchain) docker container: to run `agd status`, enter `yarn docker:bash` followed by `agd status`; or use `docker-compose exec agd agd status`.
21+
- Install from an [agoric-sdk release](https://github.com/Agoric/agoric-sdk/releases).
22+
23+
:::
24+
25+
If we invoke `agd` without arguments, it prints a list of available commands including:
26+
27+
```
28+
Available Commands:
29+
30+
help Help about any command
31+
keys Manage your application's keys
32+
query Querying subcommands
33+
status Query remote node for status
34+
tx Transactions subcommands
35+
version Print the application binary version information
36+
37+
Flags:
38+
-h, --help help for agd
39+
--home string directory for config and data (default $HOME)
40+
```
41+
42+
## Query Commands
43+
44+
In most cases, `agd query ...` is followed by a module name such as `bank`. An exception is `agd status`:
45+
46+
### agd status
47+
48+
Query remote node for status
49+
50+
Example:
51+
52+
```console
53+
$ agd status
54+
{"NodeInfo":{"protocol_version":{"p2p":"8","block":"11" ... }}}
55+
```
56+
57+
::: tip Formatting with jq
58+
59+
For pretty-printed JSON, or to select parts, pipe the output through [jq](https://jqlang.github.io/jq/).
60+
61+
```console
62+
$ agd status | jq .ValidatorInfo
63+
```
64+
65+
```json
66+
{
67+
"Address": "B4167E20C19D9B30ACD93865B854555D3823B31C",
68+
"PubKey": {
69+
"type": "tendermint/PubKeyEd25519",
70+
"value": "F9rO2FZ5sliRSRUVYnwWYVS0Ptf8Ll1dIOb6SQkgmTA="
71+
},
72+
"VotingPower": "5000"
73+
}
74+
```
75+
76+
:::
77+
78+
The query goes to a local node at `tcp://localhost:26657` by default. To use another node:
79+
80+
```console
81+
$ agd status --node https://devnet.rpc.agoric.net:443
82+
{"NodeInfo":{"protocol_version":{"p2p":"8","block":"11" ... }}}
83+
```
84+
85+
::: tip Port is required
86+
87+
Typically, `:443` can be left implicit in `https` URLs.
88+
But not here. Without it, we get:
89+
90+
```
91+
Error: post failed: Post "https://devnet.rpc.agoric.net": dial tcp: address devnet.rpc.agoric.net: missing port in address
92+
```
93+
94+
:::
95+
96+
### agd query bank balances
97+
98+
Query for account balances by address
99+
100+
Example:
101+
102+
```
103+
$ addr=agoric14pfrxg63jn6ha0cp6wxkm4nlvswtscrh2pymwm
104+
$ agd query bank balances $addr
105+
balances:
106+
- amount: "331000000"
107+
denom: ubld
108+
- amount: "4854000000"
109+
denom: uist
110+
```
111+
112+
To get **JSON output** rather than YAML:
113+
114+
```console
115+
$ agd query bank balances $addr -o json
116+
{"balances":[{"denom":"ubld","amount":"331000000"},{"denom":"uist","amount":"4854000000"}],...}
117+
```
118+
119+
### agd query gov proposals
120+
121+
Query for a all paginated proposals that match optional filters:
122+
123+
Example:
124+
125+
```
126+
$ agd query gov proposals --output json | \
127+
jq -c '.proposals[] | [.proposal_id,.voting_end_time,.status]'
128+
["1","2023-11-14T17:32:16.665791640Z","PROPOSAL_STATUS_PASSED"]
129+
["2","2023-11-14T17:40:16.450879296Z","PROPOSAL_STATUS_PASSED"]
130+
["3","2023-11-14T17:44:37.432643476Z","PROPOSAL_STATUS_PASSED"]
131+
```
132+
133+
## Transaction Commands
134+
135+
Making transactions requires setting up an **account** with a private key for signing. The [basic dapp local chain](../getting-started/#starting-a-local-agoric-blockchain) container has a number of keys set up for use with `--keyring-backend=test`. Use `agd keys list --keyring-backend=test` to see them.
136+
137+
For accounts that control real negotiable assets, using
138+
a consumer grade wallet such as Keplr is more straightforward.
139+
_Consider a hardware wallet such as a Ledger as well._
140+
141+
### agd tx bank send
142+
143+
Send funds from one account to another.
144+
145+
```
146+
$ src=agoric14pfrxg63jn6ha0cp6wxkm4nlvswtscrh2pymwm
147+
$ dest=agoric1a3zu5aqw255q0tuxzy9aftvgheekw2wedz3xwq
148+
$ amt=12000000ubld
149+
$ agd tx bank send $src $dest $amt \
150+
--keyring-backend=test --chain-id=agoriclocal \
151+
--gas=auto --gas-adjustment=1.2 \
152+
--yes -b block
153+
```
154+
155+
As usual, use `agd tx bank send --help` for documentation on
156+
flags such as `--yes`, `-b`, etc.
157+
158+
### agd tx swingset install-bundle
159+
160+
```
161+
agd tx swingset install-bundle --compress "@bundle1.json" \
162+
--from user1 --keyring-backend=test --gas=auto \
163+
--chain-id=agoriclocal -bblock --yes -o json
164+
```
165+
166+
See also the [Agoric Gov Proposal Builder](https://cosgov.org/) web interface, especially for understanding storage fees.
167+
168+
### agd tx gov submit-proposal swingset-core-eval
169+
170+
Usage:
171+
172+
```sh
173+
agd tx gov submit-proposal swingset-core-eval [[permit.json] [code.js]]... [flags]
174+
```
175+
176+
Example:
177+
178+
```
179+
$ SCRIPT=start-game1.js
180+
$ PERMIT=start-game1-permit.json
181+
agd tx gov submit-proposal swingset-core-eval "$PERMIT" "$SCRIPT" \
182+
--title="Start Game Place Contract" --description="Evaluate $SCRIPT" \
183+
--deposit=10000000ubld --gas=auto --gas-adjustment=1.2 \
184+
--from user1 --chain-id agoriclocal --keyring-backend=test \
185+
--yes -b block
186+
```
187+
188+
The [Agoric Gov Proposal Builder](https://cosgov.org/) web interface provides a nice interface for this as well.

0 commit comments

Comments
 (0)