docs: add spec files

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 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

spec/02-messages.md

@@ -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

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": "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`

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": [
+ "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