From e00f6bfe13f16e57c6d51215e1942dc183cabc87 Mon Sep 17 00:00:00 2001 From: Julian Kocher Date: Thu, 29 Aug 2024 04:50:26 -0400 Subject: [PATCH] docs: add spec files (#17) Co-authored-by: John Letey --- x/forwarding/spec/01-state.md | 79 ++++++++++++++++ x/forwarding/spec/02-messages.md | 77 ++++++++++++++++ x/forwarding/spec/03-events.md | 84 +++++++++++++++++ x/forwarding/spec/04-queries.md | 152 +++++++++++++++++++++++++++++++ x/forwarding/spec/05-cli.md | 70 ++++++++++++++ 5 files changed, 462 insertions(+) create mode 100644 x/forwarding/spec/01-state.md create mode 100644 x/forwarding/spec/02-messages.md create mode 100644 x/forwarding/spec/03-events.md create mode 100644 x/forwarding/spec/04-queries.md create mode 100644 x/forwarding/spec/05-cli.md diff --git a/x/forwarding/spec/01-state.md b/x/forwarding/spec/01-state.md new file mode 100644 index 0000000..931b112 --- /dev/null +++ b/x/forwarding/spec/01-state.md @@ -0,0 +1,79 @@ +# 01_state + +## Overview + +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. + +### 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": "noble1...", + "pub_key": null, + "account_number": "0", + "sequence": "0" + }, + "channel": "channel-0", + "recipient": "cosmos1...", + "created_at": "1620000000", + "fallback": "noble1..." +} +``` + +#### Fields + +- **BaseAccount**: inherits from `cosmos.auth.v1beta1.BaseAccount` +- **channel**: specifies the IBC channel through which tokens are forwarded +- **recipient**: the address that receives the forwarded tokens +- **created_at**: block height 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 actions. + +#### Structure + +```Go +{ + "allowed_denoms": [ + "ausdy", + "uusdc" + ], + "num_of_accounts": { + "channel-0": "1", + "channel-1": "1" + }, + "num_of_forwards": { + "channel-0": "1", + "channel-1": "1" + }, + "total_forwarded": { + "channel-0": "1000000ausdy", + "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 actions +- **total_forwarded**: a map linking channel IDs to the total amount (per 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 diff --git a/x/forwarding/spec/02-messages.md b/x/forwarding/spec/02-messages.md new file mode 100644 index 0000000..553bb53 --- /dev/null +++ b/x/forwarding/spec/02-messages.md @@ -0,0 +1,77 @@ +# 02_messages + +## Overview + +The `x/forwarding` module defines several messages concerning management of forwarding accounts and allowed denominations for automatic forwarding. These messages allow users to register and clear forwarding accounts, and an authority to update the list of denominations that can be forwarded. + +### MsgRegisterAccount + +When `MsgRegisterAccount` is submitted, it creates a new forwarding account for a specified IBC channel. The message ensures that received tokens are automatically routed to the `recipient` address, with a fallback option if the primary routing fails. The `signer` is the native address of the account registering the forwarding account. The `fallback` must be a native address. +#### Structure + +```Go +{ + "type": "noble/forwarding/RegisterAccount", + "value": { + "signer": "noble1...", + "recipient": "cosmos1...", + "channel": "channel-0", + "fallback": "noble1..." + } +} +``` + +#### Fields + +- **signer**: the address of the account that is registering the forwarding account +- **recipient**: the address where forwarded tokens will be sent +- **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 tokens to the `fallback` address. If `fallback` is `false`, tokens attempt to send at the end of the current block. + +#### Structure + +```Go +{ + "type": "noble/forwarding/ClearAccount", + "value": { + "signer": "noble1...", + "address": "noble1...", + "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 receiving tokens + + +### MsgSetAllowedDenoms + +`MsgSetAllowedDenoms` is used to configure or update the list of token denominations that are allowed for automatic forwarding. This is important for maintaining control over which assets are eligible for forwarding, ensuring that only approved tokens are routed. +#### Structure + +```Go +{ + "type": "noble/forwarding/SetAllowedDenoms", + "value": { + "signer": "noble1...", + "denoms": [ + "ausdy", + "uusdc" + ] + } +} +``` + +#### Fields + +- **signer**: the address authorized to update the list of allowed denominations +- **denoms**: a list of new denominations that are allowed for forwarding diff --git a/x/forwarding/spec/03-events.md b/x/forwarding/spec/03-events.md new file mode 100644 index 0000000..c122f67 --- /dev/null +++ b/x/forwarding/spec/03-events.md @@ -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": "noble1...", + "channel": "channel-0", + "recipient": "cosmos1...", + "fallback": "noble1..." + } +} +``` + +#### 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": "noble1...", + "recipient": "noble1..." + } +} +``` + +#### 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": ["ausdy", "uusdc"], + "current_denoms": ["ausdy", "uusdc", "ueure"] + } +} +``` + +#### 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` \ No newline at end of file diff --git a/x/forwarding/spec/04-queries.md b/x/forwarding/spec/04-queries.md new file mode 100644 index 0000000..41fe6ae --- /dev/null +++ b/x/forwarding/spec/04-queries.md @@ -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": [ + "ausdy", + "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": "noble1..." + } +} +``` + +#### Response + +```Go +{ + "type": "noble/forwarding/v1/QueryAddressResponse", + "value": { + "address": "noble1...", + "exists": true + } +} +``` + +#### Fields + +- **channel**: the IBC channel through which tokens 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": "1000000ausdy" + }, + "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": "ausdy", + "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 tokens on the channel +- **total_forwarded**: the total amount of assets forwarded on the channel, delineated by denomination \ No newline at end of file diff --git a/x/forwarding/spec/05-cli.md b/x/forwarding/spec/05-cli.md new file mode 100644 index 0000000..0376401 --- /dev/null +++ b/x/forwarding/spec/05-cli.md @@ -0,0 +1,70 @@ +# 05_cli + +## Overview + +The CLI commands for the `x/forwarding` module allow users to query information and execute transactions. + +### Query Commands + +#### Query Allowed Denoms + +Queries the list of allowed denominations. + +```Go +nobled query forwarding denoms +``` + +#### Query Forwarding Address + +Queries the address of a forwarding account based on the specified IBC channel, recipient, and fallback address. + +```Go +nobled query forwarding address [channel] [recipient] [fallback] +nobled query forwarding address channel-0 cosmos1... noble1... +``` + +#### Query Forwarding Stats + +Queries general forwarding statistics across all channels. + +```Go +nobled query forwarding stats +``` + +#### Query Forwarding Stats by Channel + +Queries general forwarding statistics for a specific IBC channel. + +```Go +nobled query forwarding stats [channel] +nobled query forwarding stats channel-0 +``` + +### Transaction Commands + +#### Register Forwarding Account + +Registers a new forwarding account with the specified recipient address, IBC channel, and fallback address. + +```Go +nobled tx forwarding register-account [recipient] [channel] [fallback] --from [signer] +nobled tx forwarding register-account cosmos1... channel-0 noble1... --from mywallet +``` + +#### Clear Forwarding Account + +Clears a forwarding account, sending any remaining packets to the fallback address. + +```Go +nobled tx forwarding clear-account [address] [fallback] --from [signer] +nobled tx forwarding clear-account noble1... true --from mywallet +``` + +#### Set Allowed Denoms + +Sets the list of allowed denominations for forwarding within the module. + +```bash +nobled tx forwarding set-allowed-denoms [denoms] --from [authority] +nobled tx forwarding set-allowed-denoms uatom uusdc --from noble1... +``` \ No newline at end of file