Transaction validation & processing

Concept

The Auth module in KIRA extends the functionality of the Cosmos SDK's auth module, focusing on validating and processing transactions within the network. It utilizes a set of AnteDecorators to perform basic transaction validity checks before they are included in the blockchain. These checks involve verifying signatures, ensuring correct nonces, and validating auxiliary fields. The Auth module is also responsible for managing accounts, including their creation, storage, and querying, as well as maintaining associated account information.

KIRA enriches the standard handlers by introducing custom decorators tailored to its network requirements such as custody rules, poor network conditions and token whitelist/blacklist enforcement.. One key area is fee processing; since KIRA does not have a concept of gas fees, it implements specific decorators for this purpose. More information on KIRA's fee processing can be found in the Fee processing module.

Governance

Currently, there is no mechanism implemented to change the Auth module parameters through governance. These parameters are initialized during the application setup, and there is no built-in procedure available to modify them subsequently. 

Parameters

All parameters pertaining to gas fees are obsolete.

NAME	TYPE	EXAMPLE	DESCRIPTION
max_memo_characters	uint64	512	The maximum permitted number of characters in the memo of a transaction
tx_sig_limit	uint64	7	The maximum number of signers for a transaction. A single transaction can have multiple messages and multiple signers
tx_size_cost_per_byte	uint64	10	The cost per byte used to compute the gas consumption of a transaction. TxSizeCostPerByte * txsize
sig_verify_cost_ed25519	uint64	590	The gas cost for verifying ED25519 signatures
sig_verify_cost_secp256k1	uint64	1000	The gas cost for verifying Secp256k1 signatures

Standard Decorators

These are auth's standard AnteDecorators that are chained together in a specific order to form an AnteHandler

DECORATOR	DESCRIPTION
SetUpContextDecorator	Sets up the context and gas meter for transactions.
RejectExtensionOptionsDecorator	Rejects extension options in protobuf transactions.
MempoolFeeDecorator	Checks if transaction fees meet the minimum fee requirements during CheckTx.
ValidateBasicDecorator	Validates transaction basics.
TxTimeoutHeightDecorator	Checks for transaction height timeouts.
ValidateMemoDecorator	Validates transaction memos.
ConsumeGasTxSizeDecorator	Consumes gas proportional to the transaction size.
DeductFeeDecorator	Deducts transaction fees from the signer's account (or fee granter's account if fee grant module is enabled).
SetPubKeyDecorator	Sets public keys for signers if not already set in the state machine.
ValidateSigCountDecorator	Validates the number of signatures in the transaction.
SigGasConsumeDecorator	Consumes gas for each signature.
SigVerificationDecorator	Verifies that all signatures are valid.
IncrementSequenceDecorator	Increments account sequence numbers for each signer to prevent replay attacks.

Custom Decorators

These are KIRA’s custom AnteDecorators

DECORATOR	DESCRIPTION	MODULE
CustodyDecorator	This decorator enforces custody rules for users, such as requiring them to have a valid key or a minimum reward amount when sending a transaction. It also checks whether they're using a whitelist, and if so, whether the recipients are on that whitelist	Custody Module
ZeroGasMeterDecorator	This decorator bypasses gas consumption for transactions by setting the gas limit to 0 and indicating no gas is consumed during processing	Fee processing
ValidateFeeRangeDecorator	This decorator checks if the transaction fee is within the range defined by the network properties. If the fee is too high or too low, it returns an error	Fee processing
ExecutionFeeRegistrationDecorator	This decorator manages the execution fee return process based on the success or failure of a message execution in a block	Fee processing
PoorNetworkManagementDecorator	Handles the allowed messages when the network is in a poor state	Poor Network Conditions
BlackWhiteTokensCheckDecorator	Checks and prevents transactions involving frozen tokens based on the token blacklist and whitelist	Governance-regulated foreign token transfers

Syntax & Examples

Each CLI command and proposal process in KIRA requires specific permissions. These permissions must be added to the account's whitelist or obtained as sudo permissions for direct changes. Refer to the Roles & Permissions documentation for more details. $SIGNER represents the transaction signer's account name or address. For instructions on setting common flags as environment variables, such as $FLAGS_TX and $FLAGS_QR, see the CLI flags configuration section

Governance

N/A

Transactions

Sign a transaction

Sign transactions that were generated offline using the sign command.

Bash

Copy

sekaid tx sign \
--from=$SIGNER $FLAGS_TX \
tx.json > tx.signed.json

Sign multiple transactions

Sign multiple offline generated transactions (-generate-only flag) using the sign-batch command. Transactions can be in one file (one tx per line) or in multiple files. For combining the signed transactions into one transactions, use the --append flag.

Bash

Copy

sekaid tx sign-batch \
--from=$SIGNER $FLAGS_TX \
txs.json > tx.signed.json

or

Bash

Copy

sekaid tx sign-batch \
--from=$SIGNER $FLAGS_TX \
tx1.json tx2.json tx3.json > tx.signed.json

Multi-sign a transaction

Sign transactions generated offline (-generate-only flag) by a multisig account using the multi-sign command. Where multisigk1k2k3 is the multisig account address, k1sig.json is the signature of the first signer, k2sig.json is the signature of the second signer, and k3sig.json is the signature of the third signer.

Bash

Copy

sekaid tx multisign \
$FLAGS_TX transaction.json multisigk1k2k3 k1sig.json k2sig.json k3sig.json

Multi-sign a batch of transaction

The multisign-batch works the same way as sign-batch, but for multisig accounts. With the difference that the --append flag does not exist.

Bash

Copy

sekaid tx multisign-batch \
$FLAGS_TX transactions.json multisigk1k2k3 k1sigs.json k2sigs.json k3sig.json

Validate transaction signatures

Validate the signatures of a signed transaction using the validate-signatures command.

Bash

Copy

sekaid tx validate-signatures \
$FLAGS_TX tx.signed.json

Broadcast a transaction

Broadcast a signed transaction to the network using the broadcast command.

Bash

Copy

sekaid tx broadcast \
$FLAGS_TX tx.signed.json

Aux-to-fee

The aux-to-fee command includes the aux signer data in the tx, broadcasts the tx, and sends the tip amount to the broadcaster. Learn more about tip transaction.

Bash

Copy

sekaid tx aux-to-fee \
$FLAGS_TX tx.aux.signed.json

Queries

Account query

Query an account by its address using the account command.

Bash

Copy

sekaid query auth account $ADDR $FLAGS_QR

Query all accounts

Use the accounts command to query all available accounts.

Bash

Copy

sekaid query auth accounts $FLAGS_QR

Query auth parameters

Query the current auth parameters using the params command.

Bash

Copy

sekaid query auth params $FLAGS_QR