Skip to content

Commit

Permalink
docs: added initial spec files
Browse files Browse the repository at this point in the history
  • Loading branch information
twothirtyfive committed Aug 19, 2024
1 parent 86712c4 commit 5633fda
Show file tree
Hide file tree
Showing 5 changed files with 464 additions and 0 deletions.
79 changes: 79 additions & 0 deletions spec/01-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 01_state

## Overview

The `x/forwarding` module maintains state related to forwarding accounts, which are specialized accounts used to route IBC packets through predefined channels. The state contains account details, channel information, and statistics related to forwarding operations.

### ForwardingAccount

The `ForwardingAccount` structure stores the data needed for forwarding. This includes routing information, account creation details, and a fallback address.

#### Structure

```Go
{
"BaseAccount": {
"address": "cosmos1...",
"pub_key": null,
"account_number": "0",
"sequence": "0"
},
"channel": "channel-0",
"recipient": "cosmos1...",
"created_at": "1620000000",
"fallback": "cosmos1..."
}
```

#### Fields

- **BaseAccount**: inherits from `cosmos.auth.v1beta1.BaseAccount`
- **channel**: specifies the IBC channel through which packets are forwarded
- **recipient**: the address that receives the forwarded packets
- **created_at**: timestamp at creation
- **fallback**: a fallback address to be used if forwarding to the primary recipient fails

#### State Update

The state is updated by the following messages:
- **`MsgRegisterAccount`**: updates the `ForwardingAccount` state by creating a new account
- **`MsgClearAccount`**: updates the `ForwardingAccount` state by clearing an account

### Genesis State

The genesis state of the `x/forwarding` module sets up the initial configuration, including which denominations are allowed for forwarding and the initial statistics related to registered accounts and forwarding transactions.

#### Structure

```Go
{
"allowed_denoms": [
"uatom",
"uusdc"
],
"num_of_accounts": {
"channel-0": "1",
"channel-1": "1"
},
"num_of_forwards": {
"channel-0": "1",
"channel-1": "1"
},
"total_forwarded": {
"channel-0": "1000000uatom",
"channel-1": "500000uusdc"
}
}
```

#### Fields

- **allowed_denoms**: a list of denominations that are allowed to be forwarded
- **num_of_accounts**: a map linking channel IDs to the number of registered forwarding accounts
- **num_of_forwards**: a map linking channel IDs to the number of forwarding transactions
- **total_forwarded**: a map linking channel IDs to the total amount (of denom) forwarded through the channel

### State Update

The state is updated by the following messages:
- **`MsgSetAllowedDenoms`**: updates the `allowed_denoms` field, changing which denominations are permitted for forwarding
79 changes: 79 additions & 0 deletions spec/02-messages.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 02_messages

## Overview

The `x/forwarding` module defines several messages concerning management of forwarding accounts and allowed denominations for IBC packet forwarding. These messages allow users to register and clear forwarding accounts, and update the list of denominations that can be forwarded.

### MsgRegisterAccount

When `MsgRegisterAccount` is submitted, it creates a new forwarding account on the specified IBC channel. The message ensures that IBC packets are routed to the `recipient` address, with a fallback option if the primary routing fails. The `signer` is the address of the account who controls the forwarding account. The `fallback` must be a native address.

#### Structure

```Go
{
"type": "noble/forwarding/MsgRegisterAccount",
"value": {
"signer": "cosmos1...",
"recipient": "cosmos1...",
"channel": "channel-0",
"fallback": "cosmos1..."
}
}
```

#### Fields

- **signer**: the address of the account that is registering the forwarding account
- **recipient**: the address where forwarded packets will be delivered
- **channel**: the IBC channel through which the forwarding occurs
- **fallback**: the fallback address to use if forwarding to the primary recipient fails


### MsgClearAccount

`MsgClearAccount` is used to clear a non-empty forwarding account, returning packets to the `fallback` address. If `fallback` is `false`, packets attempt to send at the end of the next block. The `signer` must have the necessary authority to perform this action.

#### Structure

```Go
{
"type": "noble/forwarding/MsgClearAccount",
"value": {
"signer": "cosmos1...",
"address": "cosmos1...",
"fallback": true
}
}
```

#### Fields

- **signer**: the address of the account that is clearing the forwarding account
- **address**: the address of the forwarding account to be cleared
- **fallback**: a boolean indicating whether to use the fallback address for remaining packets


### MsgSetAllowedDenoms

`MsgSetAllowedDenoms` is used to configure or update the list of token denominations that are allowed for IBC packet forwarding. This is important for maintaining control over which assets are eligible for forwarding, ensuring that only approved tokens are transferred.

#### Structure

```Go
{
"type": "noble/forwarding/MsgSetAllowedDenoms",
"value": {
"signer": "cosmos1...",
"denoms": [
"uatom",
"uusdc"
]
}
}
```

#### Fields

- **signer**: the address authorized to update the list of allowed denominations
- **denoms**: a list of new denominations that are allowed for forwarding
84 changes: 84 additions & 0 deletions spec/03-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# 03_events

## Overview

The `x/forwarding` module emits events for actions such as registration or clearing of forwarding accounts and updates to the list of allowed denominations.

### AccountRegistered

`AccountRegistered` is emitted when a new forwarding account is registered.

#### Structure

```Go
{
"type": "noble/forwarding/v1/AccountRegistered",
"attributes": {
"address": "cosmos1...",
"channel": "channel-0",
"recipient": "cosmos1...",
"fallback": "cosmos1..."
}
}
```

#### Fields

- **address**: the address of the newly registered forwarding account
- **channel**: the IBC channel used for forwarding
- **recipient**: the recipient address
- **fallback**: the fallback address to use if the primary forwarding fails

#### Emitted By

- **Transaction**: `noble.forwarding.v1.MsgRegisterAccount`

### AccountCleared

`AccountCleared` is emitted when a forwarding account is cleared.

#### Structure

```Go
{
"type": "noble/forwarding/v1/AccountCleared",
"attributes": {
"address": "cosmos1...",
"recipient": "cosmos1..."
}
}
```

#### Fields

- **address**: the address of the cleared forwarding account
- **recipient**: the recipient address if the fallback is used

#### Emitted By

- **Transaction**: `noble.forwarding.v1.MsgClearAccount`

### AllowedDenomsConfigured

`AllowedDenomsConfigured` is emitted whenever the list of allowed denominations is updated.

#### Structure

```Go
{
"type": "noble/forwarding/v1/AllowedDenomsConfigured",
"attributes": {
"previous_denoms": ["uatom", "uusdc"],
"current_denoms": ["uatom", "uusdc", "uiris"]
}
}
```

#### Fields

- **previous_denoms**: the list of denominations allowed before the update
- **current_denoms**: the newly configured list of allowed denominations

#### Emitted By

- **Transaction**: `noble.forwarding.v1.MsgSetAllowedDenoms`
152 changes: 152 additions & 0 deletions spec/04-queries.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# 04_queries

## Overview

The `x/forwarding` module provides several gRPC and REST query endpoints to retrieve information about allowed denominations, forwarding accounts, and statistics.

### QueryDenoms

`QueryDenoms` retrieves the list of denominations that are currently allowed for forwarding within the module.

#### Request

```Go
{
"type": "noble/forwarding/v1/QueryDenomsRequest",
"value": {}
}
```

#### Response

```Go
{
"type": "noble/forwarding/v1/QueryDenomsResponse",
"value": {
"allowed_denoms": [
"uatom",
"uusdc"
]
}
}
```

#### Fields

- **allowed_denoms**: a list of denominations that are currently allowed for forwarding

### QueryAddress

`QueryAddress` retrieves the address of a forwarding account based on the specified IBC channel, recipient, and fallback address

#### Request

```Go
{
"type": "noble/forwarding/v1/QueryAddressRequest",
"value": {
"channel": "channel-0",
"recipient": "cosmos1...",
"fallback": "cosmos1..."
}
}
```

#### Response

```Go
{
"type": "noble/forwarding/v1/QueryAddressResponse",
"value": {
"address": "cosmos1...",
"exists": true
}
}
```

#### Fields

- **channel**: the IBC channel through which packets are forwarded
- **recipient**: the recipient address
- **fallback**: the fallback address to use if forwarding to the primary recipient fails
- **address**: the forwarding account's address
- **exists**: a boolean indicating whether the forwarding account exists

### QueryStats

`QueryStats` retrieves statistics related to forwarding operations across all channels

#### Request

```Go
{
"type": "noble/forwarding/v1/QueryStatsRequest",
"value": {}
}
```

#### Response

```Go
{
"type": "noble/forwarding/v1/QueryStatsResponse",
"value": {
"stats": {
"channel-0": {
"num_of_accounts": "1",
"num_of_forwards": "1",
"total_forwarded": "1000000uatom"
},
"channel-1": {
"num_of_accounts": "1",
"num_of_forwards": "1",
"total_forwarded": "500000uusdc"
}
}
}
}
```

#### Fields

- **stats**: a map containing stats related to the forwarding, delineated by channel

### QueryStatsByChannel

`QueryStatsByChannel` retrieves statistics for a given IBC channel.

#### Request

```Go
{
"type": "noble/forwarding/v1/QueryStatsByChannelRequest",
"value": {
"channel": "channel-0"
}
}
```

#### Response

```Go
{
"type": "noble/forwarding/v1/QueryStatsByChannelResponse",
"value": {
"num_of_accounts": "10",
"num_of_forwards": "100",
"total_forwarded": [
{
"denom": "uatom",
"amount": "1000000"
}
]
}
}
```

#### Fields

- **channel**: the IBC channel for which statistics are being retrieved
- **num_of_accounts**: the number of registered accounts on the channel
- **num_of_forwards**: the number of forwarded packets on the channel
- **total_forwarded**: the total amount of assets forwarded on the channel, delineated by denomination
Loading

0 comments on commit 5633fda

Please sign in to comment.