tx.proto

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

import "cosmos_proto/cosmos.proto";
import "amino/amino.proto";
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";
import "google/protobuf/timestamp.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;
}

// SignDocDirectAux is the type used for generating sign bytes for
// SIGN_MODE_DIRECT_AUX.
message SignDocDirectAux {
  option (cosmos_proto.message_added_in) = "cosmos-sdk 0.46";
  // 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;

  // tips have been deprecated and should not be used
  Tip tip = 6 [deprecated = true];
}

// 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_height is the block height after which this transaction will not
  // be processed by the chain.
  uint64 timeout_height = 3;

  // unordered, when set to true, indicates that the transaction signer(s)
  // intend for the transaction to be evaluated and executed in an un-ordered
  // fashion. Specifically, the account's nonce will NOT be checked or
  // incremented, which allows for fire-and-forget as well as concurrent
  // transaction execution.
  //
  // Note, when set to true, the existing 'timeout_height' value must
  // be set and will be used to correspond to a time_stamp in which the transaction is deemed
  // valid.
  bool unordered = 4;

  // timeout_timestamp is the block time after which this transaction will not
  // be processed by the chain.
  //
  // Note, if unordered=true this value MUST be set
  // and will act as a short-lived TTL in which the transaction is deemed valid
  // and kept in memory to prevent duplicates.
  google.protobuf.Timestamp timeout_timestamp = 5 [(gogoproto.nullable) = true, (gogoproto.stdtime) = true];

  // 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;
}

// TxBodyCompat is the body of a transaction that all signers sign over.
// This message is used to represent the transaction body before the unordered
// features was added. It is used to support backwards compatibility when user a newer
// client with an older chain.
message TxBodyCompat {
  // 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_height 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 transactions fees paid in another denom.
  //
  // This field is ignored if the chain didn't enable tips, i.e. didn't add the
  // `TipDecorator` in its posthandler.
  Tip tip = 3 [deprecated = true, (cosmos_proto.field_added_in) = "cosmos-sdk 0.46"];
}

// 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 minimum 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",
    (amino.dont_omitempty)   = true,
    (amino.encoding)         = "legacy_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 [(cosmos_proto.scalar) = "cosmos.AddressString"];

  // 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 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

// Tip is the tip used for meta-transactions.
message Tip {
  option deprecated                      = true;
  option (cosmos_proto.message_added_in) = "cosmos-sdk 0.46";
  // amount is the amount of the tip
  repeated cosmos.base.v1beta1.Coin amount = 1 [
    (gogoproto.nullable)     = false,
    (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins",
    (amino.dont_omitempty)   = true,
    (amino.encoding)         = "legacy_coins"
  ];
  // tipper is the address of the account paying for the tip
  string tipper = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
}

// AuxSignerData is the intermediary format that an auxiliary signer (e.g. a
// tipper) builds and sends to the fee payer (who will build and broadcast the
// actual tx). AuxSignerData is not a valid tx in itself, and will be rejected
// by the node if sent directly as-is.
message AuxSignerData {
  option (cosmos_proto.message_added_in) = "cosmos-sdk 0.46";

  // address is the bech32-encoded address of the auxiliary signer. If using
  // AuxSignerData across different chains, the bech32 prefix of the target
  // chain (where the final transaction is broadcasted) should be used.
  string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  // sign_doc is the SIGN_MODE_DIRECT_AUX sign doc that the auxiliary signer
  // signs. Note: we use the same sign doc even if we're signing with
  // LEGACY_AMINO_JSON.
  SignDocDirectAux sign_doc = 2;
  // mode is the signing mode of the single signer.
  cosmos.tx.signing.v1beta1.SignMode mode = 3;
  // sig is the signature of the sign doc.
  bytes sig = 4;
}