docs: add spec files (#17)

Co-authored-by: John Letey <[email protected]>

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

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

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`

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