Skip to content

Commit 63fa332

Browse files
twothirtyfivetwothirtyfive
committed
moved /spec files to proper location
1 parent f83bce6 commit 63fa332

File tree

5 files changed

+464
-0
lines changed

5 files changed

+464
-0
lines changed

‎x/forwarding/spec/01-state.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 01_state
2+
3+
## Overview
4+
5+
The `x/forwarding` module maintains state related to forwarding accounts, which are specialized accounts used to automatically route tokens from Noble through predefined channels. The state contains account details, channel information, and statistics related to forwarding operations.
6+
7+
### ForwardingAccount
8+
9+
The `ForwardingAccount` structure stores the data needed for forwarding. This includes routing information, account creation details, and a fallback address.
10+
11+
#### Structure
12+
13+
```Go
14+
{
15+
"BaseAccount": {
16+
"address": "noble1...",
17+
"pub_key": null,
18+
"account_number": "0",
19+
"sequence": "0"
20+
},
21+
"channel": "channel-0",
22+
"recipient": "cosmos1...",
23+
"created_at": "1620000000",
24+
"fallback": "noble1..."
25+
}
26+
```
27+
28+
#### Fields
29+
30+
- **BaseAccount**: inherits from `cosmos.auth.v1beta1.BaseAccount`
31+
- **channel**: specifies the IBC channel through which tokens are forwarded
32+
- **recipient**: the address that receives the forwarded tokens
33+
- **created_at**: timestamp at creation
34+
- **fallback**: a fallback address to be used if forwarding to the primary recipient fails
35+
36+
#### State Update
37+
38+
The state is updated by the following messages:
39+
- **`MsgRegisterAccount`**: updates the `ForwardingAccount` state by creating a new account
40+
- **`MsgClearAccount`**: updates the `ForwardingAccount` state by clearing an account
41+
42+
### Genesis State
43+
44+
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.
45+
46+
#### Structure
47+
48+
```Go
49+
{
50+
"allowed_denoms": [
51+
"uatom",
52+
"uusdc"
53+
],
54+
"num_of_accounts": {
55+
"channel-0": "1",
56+
"channel-1": "1"
57+
},
58+
"num_of_forwards": {
59+
"channel-0": "1",
60+
"channel-1": "1"
61+
},
62+
"total_forwarded": {
63+
"channel-0": "1000000uatom",
64+
"channel-1": "500000uusdc"
65+
}
66+
}
67+
```
68+
69+
#### Fields
70+
71+
- **allowed_denoms**: a list of denominations that are allowed to be forwarded
72+
- **num_of_accounts**: a map linking channel IDs to the number of registered forwarding accounts
73+
- **num_of_forwards**: a map linking channel IDs to the number of forwarding transactions
74+
- **total_forwarded**: a map linking channel IDs to the total amount (of denom) forwarded through the channel
75+
76+
### State Update
77+
78+
The state is updated by the following messages:
79+
- **`MsgSetAllowedDenoms`**: updates the `allowed_denoms` field, changing which denominations are permitted for forwarding

‎x/forwarding/spec/02-messages.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# 02_messages
2+
3+
## Overview
4+
5+
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.
6+
7+
### MsgRegisterAccount
8+
9+
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.
10+
11+
#### Structure
12+
13+
```Go
14+
{
15+
"type": "noble/forwarding/MsgRegisterAccount",
16+
"value": {
17+
"signer": "cosmos1...",
18+
"recipient": "cosmos1...",
19+
"channel": "channel-0",
20+
"fallback": "cosmos1..."
21+
}
22+
}
23+
```
24+
25+
#### Fields
26+
27+
- **signer**: the address of the account that is registering the forwarding account
28+
- **recipient**: the address where forwarded packets will be delivered
29+
- **channel**: the IBC channel through which the forwarding occurs
30+
- **fallback**: the fallback address to use if forwarding to the primary recipient fails
31+
32+
33+
### MsgClearAccount
34+
35+
`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.
36+
37+
#### Structure
38+
39+
```Go
40+
{
41+
"type": "noble/forwarding/MsgClearAccount",
42+
"value": {
43+
"signer": "cosmos1...",
44+
"address": "cosmos1...",
45+
"fallback": true
46+
}
47+
}
48+
```
49+
50+
#### Fields
51+
52+
- **signer**: the address of the account that is clearing the forwarding account
53+
- **address**: the address of the forwarding account to be cleared
54+
- **fallback**: a boolean indicating whether to use the fallback address for remaining packets
55+
56+
57+
### MsgSetAllowedDenoms
58+
59+
`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.
60+
61+
#### Structure
62+
63+
```Go
64+
{
65+
"type": "noble/forwarding/MsgSetAllowedDenoms",
66+
"value": {
67+
"signer": "cosmos1...",
68+
"denoms": [
69+
"uatom",
70+
"uusdc"
71+
]
72+
}
73+
}
74+
```
75+
76+
#### Fields
77+
78+
- **signer**: the address authorized to update the list of allowed denominations
79+
- **denoms**: a list of new denominations that are allowed for forwarding

‎x/forwarding/spec/03-events.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# 03_events
2+
3+
## Overview
4+
5+
The `x/forwarding` module emits events for actions such as registration or clearing of forwarding accounts and updates to the list of allowed denominations.
6+
7+
### AccountRegistered
8+
9+
`AccountRegistered` is emitted when a new forwarding account is registered.
10+
11+
#### Structure
12+
13+
```Go
14+
{
15+
"type": "noble/forwarding/v1/AccountRegistered",
16+
"attributes": {
17+
"address": "cosmos1...",
18+
"channel": "channel-0",
19+
"recipient": "cosmos1...",
20+
"fallback": "cosmos1..."
21+
}
22+
}
23+
```
24+
25+
#### Fields
26+
27+
- **address**: the address of the newly registered forwarding account
28+
- **channel**: the IBC channel used for forwarding
29+
- **recipient**: the recipient address
30+
- **fallback**: the fallback address to use if the primary forwarding fails
31+
32+
#### Emitted By
33+
34+
- **Transaction**: `noble.forwarding.v1.MsgRegisterAccount`
35+
36+
### AccountCleared
37+
38+
`AccountCleared` is emitted when a forwarding account is cleared.
39+
40+
#### Structure
41+
42+
```Go
43+
{
44+
"type": "noble/forwarding/v1/AccountCleared",
45+
"attributes": {
46+
"address": "cosmos1...",
47+
"recipient": "cosmos1..."
48+
}
49+
}
50+
```
51+
52+
#### Fields
53+
54+
- **address**: the address of the cleared forwarding account
55+
- **recipient**: the recipient address if the fallback is used
56+
57+
#### Emitted By
58+
59+
- **Transaction**: `noble.forwarding.v1.MsgClearAccount`
60+
61+
### AllowedDenomsConfigured
62+
63+
`AllowedDenomsConfigured` is emitted whenever the list of allowed denominations is updated.
64+
65+
#### Structure
66+
67+
```Go
68+
{
69+
"type": "noble/forwarding/v1/AllowedDenomsConfigured",
70+
"attributes": {
71+
"previous_denoms": ["uatom", "uusdc"],
72+
"current_denoms": ["uatom", "uusdc", "uiris"]
73+
}
74+
}
75+
```
76+
77+
#### Fields
78+
79+
- **previous_denoms**: the list of denominations allowed before the update
80+
- **current_denoms**: the newly configured list of allowed denominations
81+
82+
#### Emitted By
83+
84+
- **Transaction**: `noble.forwarding.v1.MsgSetAllowedDenoms`

‎x/forwarding/spec/04-queries.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# 04_queries
2+
3+
## Overview
4+
5+
The `x/forwarding` module provides several gRPC and REST query endpoints to retrieve information about allowed denominations, forwarding accounts, and statistics.
6+
7+
### QueryDenoms
8+
9+
`QueryDenoms` retrieves the list of denominations that are currently allowed for forwarding within the module.
10+
11+
#### Request
12+
13+
```Go
14+
{
15+
"type": "noble/forwarding/v1/QueryDenomsRequest",
16+
"value": {}
17+
}
18+
```
19+
20+
#### Response
21+
22+
```Go
23+
{
24+
"type": "noble/forwarding/v1/QueryDenomsResponse",
25+
"value": {
26+
"allowed_denoms": [
27+
"uatom",
28+
"uusdc"
29+
]
30+
}
31+
}
32+
```
33+
34+
#### Fields
35+
36+
- **allowed_denoms**: a list of denominations that are currently allowed for forwarding
37+
38+
### QueryAddress
39+
40+
`QueryAddress` retrieves the address of a forwarding account based on the specified IBC channel, recipient, and fallback address
41+
42+
#### Request
43+
44+
```Go
45+
{
46+
"type": "noble/forwarding/v1/QueryAddressRequest",
47+
"value": {
48+
"channel": "channel-0",
49+
"recipient": "cosmos1...",
50+
"fallback": "cosmos1..."
51+
}
52+
}
53+
```
54+
55+
#### Response
56+
57+
```Go
58+
{
59+
"type": "noble/forwarding/v1/QueryAddressResponse",
60+
"value": {
61+
"address": "cosmos1...",
62+
"exists": true
63+
}
64+
}
65+
```
66+
67+
#### Fields
68+
69+
- **channel**: the IBC channel through which packets are forwarded
70+
- **recipient**: the recipient address
71+
- **fallback**: the fallback address to use if forwarding to the primary recipient fails
72+
- **address**: the forwarding account's address
73+
- **exists**: a boolean indicating whether the forwarding account exists
74+
75+
### QueryStats
76+
77+
`QueryStats` retrieves statistics related to forwarding operations across all channels
78+
79+
#### Request
80+
81+
```Go
82+
{
83+
"type": "noble/forwarding/v1/QueryStatsRequest",
84+
"value": {}
85+
}
86+
```
87+
88+
#### Response
89+
90+
```Go
91+
{
92+
"type": "noble/forwarding/v1/QueryStatsResponse",
93+
"value": {
94+
"stats": {
95+
"channel-0": {
96+
"num_of_accounts": "1",
97+
"num_of_forwards": "1",
98+
"total_forwarded": "1000000uatom"
99+
},
100+
"channel-1": {
101+
"num_of_accounts": "1",
102+
"num_of_forwards": "1",
103+
"total_forwarded": "500000uusdc"
104+
}
105+
}
106+
}
107+
}
108+
```
109+
110+
#### Fields
111+
112+
- **stats**: a map containing stats related to the forwarding, delineated by channel
113+
114+
### QueryStatsByChannel
115+
116+
`QueryStatsByChannel` retrieves statistics for a given IBC channel.
117+
118+
#### Request
119+
120+
```Go
121+
{
122+
"type": "noble/forwarding/v1/QueryStatsByChannelRequest",
123+
"value": {
124+
"channel": "channel-0"
125+
}
126+
}
127+
```
128+
129+
#### Response
130+
131+
```Go
132+
{
133+
"type": "noble/forwarding/v1/QueryStatsByChannelResponse",
134+
"value": {
135+
"num_of_accounts": "10",
136+
"num_of_forwards": "100",
137+
"total_forwarded": [
138+
{
139+
"denom": "uatom",
140+
"amount": "1000000"
141+
}
142+
]
143+
}
144+
}
145+
```
146+
147+
#### Fields
148+
149+
- **channel**: the IBC channel for which statistics are being retrieved
150+
- **num_of_accounts**: the number of registered accounts on the channel
151+
- **num_of_forwards**: the number of forwarded packets on the channel
152+
- **total_forwarded**: the total amount of assets forwarded on the channel, delineated by denomination

0 commit comments

Comments
 (0)