Skip to content

Commit

Permalink
update masp and ibc user sections (#353)
Browse files Browse the repository at this point in the history 
update masp and ibc user sections
  • Loading branch information
@iskay
iskay authored May 31, 2024
1 parent fa84dd4 commit 0aba9d3
Show file tree
Hide file tree
Showing 15 changed files with 430 additions and 314 deletions.
6 changes: 3 additions & 3 deletions packages/docs/pages/users/_meta.json
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
{
"wallet": "Using the Namada wallet",
"transparent-accounts": "Transparent accounts",
"shielded-accounts": "The MASP",
"transparent-accounts": "Transparent Accounts",
"shielded-accounts": "MASP & Shielded Transfers",
"fees": "Fees on Namada",
"delegators": "Bonding and Proof-of-stake",
"governance": "Governance and Public Goods Funding",
"public-goods-stewards": "PGF",
"ibc": "IBC transfers",
"query": "Querying the chain"
"query": "Querying the Chain"
}
126 changes: 12 additions & 114 deletions packages/docs/pages/users/ibc.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,120 +1,18 @@
import { Callout } from 'nextra-theme-docs'

# Transferring assets over IBC
# Transferring Assets over IBC

It is possible to make ibc transfers using the Namada cli with the command `namadac ibc-transfer`. The assumed pre-requisites are that a channel has been created and Hermes is running with the proper config on two nodes.
Namada features full IBC protocol support, which means non-native assets can be brought over from any IBC compatible
chain (such as Cosmos SDK chains). As a result, users can enjoy the combined benefits of another chain's ecosystem, assets
and features with Namada's [MASP](./shielded-accounts/).

In order to conduct an IBC transfer using Namada's `ibc-transfer` command, we will need to know the `base-dir` and `node` of each instance (and other transfer parameters).
`base-dir` is the base directory of each node, see [base-dir](../operators/ledger/base-directory.mdx) for more information.
`node` is the `rpc_addr` of the relayer.
You can run
```shell
grep "rpc_addr" ${HERMES_CONFIG}
```
to find the address.
The assumed prerequisites are that an active IBC connection has been created and maintained between the two chains by
operators running relayer software such as [Hermes](https://github.com/heliaxdev/hermes).

<Callout>
**For the local node ONLY**
This section will be focused on IBC transfers from a user perspective. For info on operating an IBC relayer, see
[this](../operators/ibc.mdx) page in the Operators section.

To find your ledger address for Chain A, you can run the following command
```bash copy
export BASE_DIR_A="${HERMES}/data/namada-a/.namada"
export LEDGER_ADDRESS_A="$(grep "rpc_address" ${BASE_DIR_A}/${CHAIN_A_ID}/setup/validator-0/.namada/${CHAIN_A_ID}/config.toml)"
```
</Callout>

The [channel ID](../operators/ibc.mdx) for this chain will depend on the order in which one created the channel. Since we have only opened one channel, the `channel-id` is `channel-0`, but as more are created, these increase by index incremented by 1. The channel-id should be communicated by the relayer.

Assuming that the open channel is `channel-0`, you can save it in an environment variable by running
```bash copy
export CHANNEL_ID="channel-0"
```

The inter-blockchain transfers from Chain A can be achieved by
```bash copy
namadac --base-dir ${BASE_DIR_A}
ibc-transfer \
--amount ${AMOUNT} \
--source ${SOURCE_ALIAS} \
--receiver ${RECEIVER_RAW_ADDRESS} \
--token ${TOKEN_ALIAS} \
--channel-id ${CHANNEL_ID} \
--node ${LEDGER_ADDRESS_A}
```
Where the above variables in `${VARIABLE}` must be substituted with appropriate values. The raw address of the receiver can be found by `namadaw --base-dir ${BASE_DIR_B} address find --alias ${RECEIVER}`.

E.g.
```bash copy
namadac --base-dir ${BASE_DIR_A}
ibc-transfer \
--amount 100 \
--source albert \
--receiver atest1d9khqw36g56nqwpkgezrvvejg3p5xv2z8y6nydehxprygvp5g4znj3phxfpyv3pcgcunws2x0wwa76 \
--token nam \
--channel-id channel-0 \
--node http://127.0.0.1:27657
```

Once the transaction has been submitted, a relayer will need to relay the packet to the other chain. This is done automatically by the relayer running Hermes. If the packet is never successfully relayed, the funds are returned to the sender after a timeout. See more information in the [specs](https://specs.namada.net/modules/ibc).

## Transferring assets back from Cosmos-SDK based chains

When a transfer has been made to a Cosmos-SDK based chain, the ibc transfer is conducted as above. However, when transferring back from the cosmos-based chain, clearly the `namadac ibc-transfer` command will not work. Instead, you want to use [`gaiad`](https://github.com/cosmos/gaia).

```bash
gaiad tx ibc-transfer transfer transfer ${CHANNEL_ID} ${RECEIVER_RAW_ADDRESS} ${AMOUNT}${IBC_TOKEN_ADDRESS} --from ${COSMOS_ALIAS} --node ${COSMOS_RPC_ENDPOINT} --fees 5000uatom
```

for example:

```bash copy
gaiad tx ibc-transfer transfer transfer channel-0 atest1d9khqw368qcyx3jxxu6njs2yxs6y2sjyxdzy2d338pp5yd35g9zrv334gceng3z9gvmryv2pfdddt4 10ibc/281545A262215A2D7041CE1B518DD4754EC7097A1C937BE9D9AB6F1F11B452DD --from my-cosmos-address --node https://rpc.sentry-01.theta-testnet.polypore.xyz:443 --fees 5000uatom
```

## Shielding transfer
Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including required data. In this case, Chain B is the destination chain.
```bash copy
namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \
--output-folder-path ${OUTPUT_PATH} \
--target ${payment_addr_b} \
--token apfel \
--amount 100 \
--port-id transfer \
--channel-id channel-0 \
--node ${LEDGER_ADDRESS_B}
```
Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field. The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file path created by `namadac ibc-gen-shielded` on the destination chain.
```bash copy
namadac --base-dir ${BASE_DIR_A} ibc-transfer \
--source ${spending_key_a} \
--receiver ${payment_addr_b} \
--token apfel \
--amount 100 \
--channel-id channel-0 \
--memo-path ${memo_path} \
--node ${LEDGER_ADDRESS_A}
```

When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option.
```bash copy
memo=$(cat ${memo_path})
gaiad tx ibc-transfer transfer \
${CHANNEL_ID} \
${RECEIVER_PAYMENT_ADDRESS} \
${AMOUNT}${IBC_TOKEN_ADDRESS} \
--from ${COSMOS_ALIAS} \
--memo ${memo} \
--node ${COSMOS_RPC_ENDPOINT} \
--fees 5000uatom
```

You can do unshielding transfers over IBC without generating a proof.
```bash copy
namadac --base-dir ${BASE_DIR_A} ibc-transfer \
--source ${spending_key_a} \
--receiver ${RECEIVER_RAW_ADDRESS} \
--token nam \
--amount 100 \
--channel-id channel-0 \
--node ${LEDGER_ADDRESS_A}
```
### Resources
- [How IBC Works](https://www.ibcprotocol.dev/how-ibc-works): A brief, beginner-friendly overview of IBC
- [What is IBC?](https://tutorials.cosmos.network/academy/3-ibc/1-what-is-ibc.html): A detailed, developer-focused look
at the design and functionality of the protocol
4 changes: 4 additions & 0 deletions packages/docs/pages/users/ibc/_meta.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"shielded-ibc": "Shielded IBC",
"transparent-ibc": "Transparent IBC"
}
70 changes: 70 additions & 0 deletions packages/docs/pages/users/ibc/shielded-ibc.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
import { Callout } from 'nextra-theme-docs'

# Shielded IBC

You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the
`ibc-transfer` command in `namadac`.

This section covers sending assets to and from a shielded ( `znam` ) address.

## Prerequisites

- An active IBC connection has been created and maintained between the two chains by operators running relayer
software such as [Hermes](https://github.com/heliaxdev/hermes).
- You will need to know the corresponding channel id

## IBC transfer to a shielded address
{/* TODO: instructions are out of date? */}

Before sending your IBC transfer, you will need to generate a MASP

Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer
to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including
required data. In this case, Chain B is the destination chain.
```bash copy
namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \
--output-folder-path ${OUTPUT_PATH} \
--target ${payment_addr_b} \
--token apfel \
--amount 100 \
--port-id transfer \
--channel-id channel-0 \
--node ${LEDGER_ADDRESS_B}
```
Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field.
The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file
path created by `namadac ibc-gen-shielded` on the destination chain.
```bash copy
namadac --base-dir ${BASE_DIR_A} ibc-transfer \
--source ${spending_key_a} \
--receiver ${payment_addr_b} \
--token apfel \
--amount 100 \
--channel-id channel-0 \
--memo-path ${memo_path} \
--node ${LEDGER_ADDRESS_A}
```

When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option.
```bash copy
memo=$(cat ${memo_path})
gaiad tx ibc-transfer transfer \
${CHANNEL_ID} \
${RECEIVER_PAYMENT_ADDRESS} \
${AMOUNT}${IBC_TOKEN_ADDRESS} \
--from ${COSMOS_ALIAS} \
--memo ${memo} \
--node ${COSMOS_RPC_ENDPOINT} \
--fees 5000uatom
```

You can do unshielding transfers over IBC without generating a proof.
```bash copy
namadac --base-dir ${BASE_DIR_A} ibc-transfer \
--source ${spending_key_a} \
--receiver ${RECEIVER_RAW_ADDRESS} \
--token nam \
--amount 100 \
--channel-id channel-0 \
--node ${LEDGER_ADDRESS_A}
```
69 changes: 69 additions & 0 deletions packages/docs/pages/users/ibc/transparent-ibc.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import { Callout } from 'nextra-theme-docs'

# Transparent IBC

You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the
`ibc-transfer` command in `namadac`.

This section covers sending assets to and from a transparent ( `tnam` ) address.

## Prerequisites

- An active IBC connection has been created and maintained between the two chains by operators running relayer
software such as [Hermes](https://github.com/heliaxdev/hermes).
- You will need to know the corresponding channel id

## IBC transfers from Namada to another chain

To make an outgoing IBC transfer from a Namada transparent address:
```bash copy
namadac ibc-transfer \
--source <your-transparent-address> \
--receiver <address-on-receiving-chain> \
--token <token-address> \
--amount <amount>
--channel-id <channel-id>
```
Note:
- the `receiver` address is the address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`,
while if you're sending to a Cosmos SDK chain it might start with `cosmos...` or some other prefix.
- the `channel-id` parameter is a string, for example `channel-27`.

#### Example: Sending NAM to the Cosmos Hub
```bash copy
namadac ibc-transfer \
--source my-namada-wallet \
--receiver cosmos1y3q368qj8d2ged5xcdz96wtt3n5f9zq6ql0p7k \
--token nam \
--amount 10 \
--channel-id channel-42
```

Once the transaction has been submitted, a relayer will need to relay the packet to the other chain.
This is done automatically by the relayer running Hermes. If the packet is never successfully relayed, the funds are
returned to the sender after a timeout. See more information in the [specs](https://specs.namada.net/modules/ibc).

## Transferring assets into Namada from Cosmos SDK chains

To transfer assets back from a Cosmos SDK chain, you will post an IBC transaction on that chain using its corresponding
client software.

For the Cosmos Hub, you will use [`gaiad`](https://github.com/cosmos/gaia). Other chains will have their own corresponding client;
however all Cosmos SDK based clients will share approximately the same commands and operation. Consult the documentation
of the counterparty chain when in doubt.

#### Example: Sending ATOM from the Cosmos Hub to Namada

```bash
gaiad tx ibc-transfer transfer \
transfer \
channel-64 \
tnam1qzgmrvz0zdjtgdu7yq6hl46wdg7za2t2hg5t85c7 \
10000000uatom \
--from my-cosmos-wallet \
--fees 5000uatom
```
<Callout>
The double use of 'transfer' in the above command is not a typo. The command takes an IBC port name as one of its parameters;
and the name of the port happens to be 'transfer'.
</Callout>
30 changes: 16 additions & 14 deletions packages/docs/pages/users/query.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,53 @@
# **Query**
# Querying Overview

This is the complete query related to Namada
Querying a Namada chain is done using the client `namadac`.

Including: account,pgf,proposal,proposal-result,proposal-votes
This section details several common queries; see all available commands with `namadac --help`.

## query-account
#### query-account

```txt
namadac query-account --owner <WALLET>
```

Return the results will return the `Threshold` and `Public` key of the address.
Returns the `Threshold` and `Public` key(s) of an established account.

## query-pgf
#### query-pgf

```
namadac query-pgf
```

Return the results will return the `Pgf stewards , Reward distribution`, `Pgf fundings` key of the address.
Returns the list of PGF Stewards, their reward distribution, and active PGF streaming payments.

## query-proposal
#### query-proposal

```
namadac query-proposal --proposal-id <ID>
```

Return the results will return the PGF type of the proposal, `author`, `content`, `StartEpoch`, `EndEpoch`, `GraceEpoch`, `Status`
Returns info on a given proposal, including its type, author, content, StartEpoch, EndEpoch, GraceEpoch, and Status.

## query-proposal-result
#### query-proposal-result

```
namadac query-proposal-result --proposal-id <ID>
```

Return the results will return the outcome of the proposal, whether it's `Passed` or `Rejected`, including the total number of votes for `yay`, `nay`, `abstain`, and the threshold (fraction) of the total voting power needed to tally.
Returns the outcome of a given proposal, including whether it's Passed/Rejected, the total number of votes for yay/nay/abstain, and the threshold (fraction) of the total voting power needed to tally.

## query-proposal-votes
#### query-proposal-votes

```
namadac query-proposal-votes --proposal-id <ID>
```

Return the results of all wallets that have voted `yay` or `nay` on the proposal
Returns the results of all wallets that have voted `yay` or `nay` on the proposal

```
namadac query-proposal-votes --proposal-id <ID> --voter <WALLET>
```

Return the result of a specific wallet that has voted on a specific proposal
Returns the result of a specific wallet that has voted on a specific proposal

{/* TODO: add more queries*/}
24 changes: 21 additions & 3 deletions packages/docs/pages/users/shielded-accounts.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,26 @@
# The MASP

The multi-asset shielded pool (MASP) is a zero knowledge circuit that allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note". From the users perspective, the construction of these zero knowledge proofs occur behind the scenes.
Namada affords users data-protection through its multi-asset shielded pool (MASP), which supports shielded transfers with any native or non-native asset.
The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that
extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary
assets. All assets in the pool share the same anonymity set -- meaning that the more transactions are issued to MASP, the stronger the
data protection guarantees for all users.

The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner. This circuit is called the Convert Circuit (CC for short).
The MASP allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note".
From the users perspective, the construction of these zero knowledge proofs occur behind the scenes.

More technical details of these circuits can be found in the [specs](https://specs.namada.net) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits).
Users of the MASP are [rewarded](./shielded-accounts/shielded-rewards.mdx) for their contributions to the shielded set in the form of native protocol tokens (NAM).

### Inspiration

The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality.
In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner.
This circuit is called the Convert Circuit (CC for short).

If you are familiar with Zcash, the set of interactions you can execute with Namada's MASP are similar:
- [Shielding transfers](./shielded-accounts/shielding.mdx): transparent to shielded address
- [Shielded transfers](./shielded-accounts/shielded-transfers.mdx): shielded to shielded address
- [Unshielding transfers](./shielded-accounts/unshielding.mdx): shielded to transparent address

More technical details of these circuits can be found in the [specs](https://specs.namada.net/modules/masp) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits).

Loading

0 comments on commit 0aba9d3

Please sign in to comment.