cosmos-sdk/proto/cosmos/tx/v1beta1/tx.proto

syntax = "proto3";
package cosmos.tx.v1beta1;

import "gogoproto/gogo.proto";
import "cosmos/crypto/multisig/v1beta1/multisig.proto";
import "cosmos/base/v1beta1/coin.proto";
import "cosmos/tx/signing/v1beta1/signing.proto";
import "google/protobuf/any.proto";

option go_package = "github.com/cosmos/cosmos-sdk/types/tx";

// Tx is the standard type used for broadcasting transactions.
message Tx {
  // body is the processable content of the transaction
  TxBody body = 1;

  // auth_info is the authorization related content of the transaction,
  // specifically signers, signer modes and fee
  AuthInfo auth_info = 2;

  // signatures is a list of signatures that matches the length and order of
  // AuthInfo's signer_infos to allow connecting signature meta information like
  // public key and signing mode by position.
  repeated bytes signatures = 3;
}

// TxRaw is a variant of Tx that pins the signer's exact binary representation
// of body and auth_info. This is used for signing, broadcasting and
// verification. The binary `serialize(tx: TxRaw)` is stored in Tendermint and
// the hash `sha256(serialize(tx: TxRaw))` becomes the "txhash", commonly used
// as the transaction ID.
message TxRaw {
  // body_bytes is a protobuf serialization of a TxBody that matches the
  // representation in SignDoc.
  bytes body_bytes = 1;

  // auth_info_bytes is a protobuf serialization of an AuthInfo that matches the
  // representation in SignDoc.
  bytes auth_info_bytes = 2;

  // signatures is a list of signatures that matches the length and order of
  // AuthInfo's signer_infos to allow connecting signature meta information like
  // public key and signing mode by position.
  repeated bytes signatures = 3;
}

// SignDoc is the type used for generating sign bytes for SIGN_MODE_DIRECT.
message SignDoc {
  // body_bytes is protobuf serialization of a TxBody that matches the
  // representation in TxRaw.
  bytes body_bytes = 1;

  // auth_info_bytes is a protobuf serialization of an AuthInfo that matches the
  // representation in TxRaw.
  bytes auth_info_bytes = 2;

  // chain_id is the unique identifier of the chain this transaction targets.
  // It prevents signed transactions from being used on another chain by an
  // attacker
  string chain_id = 3;

  // account_number is the account number of the account in state
  uint64 account_number = 4;
}

// SignDocJSON is the type used for generating sign bytes for
// SIGN_MODE_DIRECT_JSON. It is designed to be serialized as proto3 JSON
// following the rules defined here:
// https://github.com/regen-network/canonical-proto3/blob/master/README.md#json.
message SignDocJSON {
  // body is the processable content of the transaction
  TxBody body = 1;

  // auth_info is the authorization related content of the transaction,
  // specifically signers, signer modes and fee
  AuthInfo auth_info = 2;

  // chain_id is the identifier of the chain this transaction targets.
  // It prevents signed transactions from being used on another chain by an
  // attacker
  string chain_id = 3;

  // account_number is the account number of the signing account in state
  uint64 account_number = 4;

  // sign_doc_sha256_hash is the SHA-256 hash of SignDoc. It is included here to
  // reduce the malleability attack surface of SIGN_MODE_DIRECT_JSON vs
  // SIGN_MODE_DIRECT to zero. Basically this means that any discrepancy between
  // protobuf bytes over the wire and protobuf bytes that are signed cannot be
  // exploited. This information is obviously redundant with information already
  // in SignDocJSON, but is included as a security check for scenarios where
  // this information may have inadvertently been excluded. We include the hash
  // of SignDoc rather than the full SignDoc bytes to reduce the size of
  // SignDocJSON for scenarios where large payloads could cause problems for
  // hardware wallets.
  bytes sign_doc_sha256_hash = 5;
}

// SignDocDirectAux is the type used for generating sign bytes for
// SIGN_MODE_DIRECT_AUX.
message SignDocDirectAux {
  // body_bytes is protobuf serialization of a TxBody that matches the
  // representation in TxRaw.
  bytes body_bytes = 1;

  // public_key is the public key of the signing account.
  google.protobuf.Any public_key = 2;

  // chain_id is the identifier of the chain this transaction targets.
  // It prevents signed transactions from being used on another chain by an
  // attacker.
  string chain_id = 3;

  // account_number is the account number of the account in state.
  uint64 account_number = 4;

  // sequence is the sequence number of the signing account.
  uint64 sequence = 5;

  // Tip is the optional tip used for meta-transactions. It should be left
  // empty if the signer is not the tipper for this transaction.
  Tip tip = 6;
}

// TxBody is the body of a transaction that all signers sign over.
message TxBody {
  // messages is a list of messages to be executed. The required signers of
  // those messages define the number and order of elements in AuthInfo's
  // signer_infos and Tx's signatures. Each required signer address is added to
  // the list only the first time it occurs.
  // By convention, the first required signer (usually from the first message)
  // is referred to as the primary signer and pays the fee for the whole
  // transaction.
  repeated google.protobuf.Any messages = 1;

  // memo is any arbitrary note/comment to be added to the transaction.
  // WARNING: in clients, any publicly exposed text should not be called memo,
  // but should be called `note` instead (see https://github.com/cosmos/cosmos-sdk/issues/9122).
  string memo = 2;

  // timeout is the block height after which this transaction will not
  // be processed by the chain
  uint64 timeout_height = 3;

  // extension_options are arbitrary options that can be added by chains
  // when the default options are not sufficient. If any of these are present
  // and can't be handled, the transaction will be rejected
  repeated google.protobuf.Any extension_options = 1023;

  // extension_options are arbitrary options that can be added by chains
  // when the default options are not sufficient. If any of these are present
  // and can't be handled, they will be ignored
  repeated google.protobuf.Any non_critical_extension_options = 2047;
}

// AuthInfo describes the fee and signer modes that are used to sign a
// transaction.
message AuthInfo {
  // signer_infos defines the signing modes for the required signers. The number
  // and order of elements must match the required signers from TxBody's
  // messages. The first element is the primary signer and the one which pays
  // the fee.
  repeated SignerInfo signer_infos = 1;

  // Fee is the fee and gas limit for the transaction. The first signer is the
  // primary signer and the one which pays the fee. The fee can be calculated
  // based on the cost of evaluating the body and doing signature verification
  // of the signers. This can be estimated via simulation.
  Fee fee = 2;

  // Tip is the optional tip used for meta-transactions.
  Tip tip = 3;
}

// SignerInfo describes the public key and signing mode of a single top-level
// signer.
message SignerInfo {
  // public_key is the public key of the signer. It is optional for accounts
  // that already exist in state. If unset, the verifier can use the required \
  // signer address for this position and lookup the public key.
  google.protobuf.Any public_key = 1;

  // mode_info describes the signing mode of the signer and is a nested
  // structure to support nested multisig pubkey's
  ModeInfo mode_info = 2;

  // sequence is the sequence of the account, which describes the
  // number of committed transactions signed by a given address. It is used to
  // prevent replay attacks.
  uint64 sequence = 3;
}

// ModeInfo describes the signing mode of a single or nested multisig signer.
message ModeInfo {
  // sum is the oneof that specifies whether this represents a single or nested
  // multisig signer
  oneof sum {
    // single represents a single signer
    Single single = 1;

    // multi represents a nested multisig signer
    Multi multi = 2;
  }

  // Single is the mode info for a single signer. It is structured as a message
  // to allow for additional fields such as locale for SIGN_MODE_TEXTUAL in the
  // future
  message Single {
    // mode is the signing mode of the single signer
    cosmos.tx.signing.v1beta1.SignMode mode = 1;
  }

  // Multi is the mode info for a multisig public key
  message Multi {
    // bitarray specifies which keys within the multisig are signing
    cosmos.crypto.multisig.v1beta1.CompactBitArray bitarray = 1;

    // mode_infos is the corresponding modes of the signers of the multisig
    // which could include nested multisig public keys
    repeated ModeInfo mode_infos = 2;
  }
}

// Fee includes the amount of coins paid in fees and the maximum
// gas to be used by the transaction. The ratio yields an effective "gasprice",
// which must be above some miminum to be accepted into the mempool.
message Fee {
  // amount is the amount of coins to be paid as a fee
  repeated cosmos.base.v1beta1.Coin amount = 1
      [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

  // gas_limit is the maximum gas that can be used in transaction processing
  // before an out of gas error occurs
  uint64 gas_limit = 2;

  // if unset, the first signer is responsible for paying the fees. If set, the specified account must pay the fees.
  // the payer must be a tx signer (and thus have signed this field in AuthInfo).
  // setting this field does *not* change the ordering of required signers for the transaction.
  string payer = 3;

  // if set, the fee payer (either the first signer or the value of the payer field) requests that a fee grant be used
  // to pay fees instead of the fee payer's own balance. If an appropriate fee grant does not exist or the chain does
  // not support fee grants, this will fail
  string granter = 4;
}

// Tip is the tip used for meta-transactions.
message Tip {
  // amount is the amount of the tip
  repeated cosmos.base.v1beta1.Coin amount = 1;
  // tipper is the address of the account paying for the tip
  string tipper = 2;
}