Generate an Unsigned Transaction and Signing Payloads

Body

application/json

ConstructionPayloadsRequest is the request to /construction/payloads. It contains the network, a slice of operations, and arbitrary metadata that was returned by the call to /construction/metadata. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.

network_identifier

object

required

The network_identifier specifies which network a particular object is associated with.

Show child attributes

network_identifier.blockchain

string

required

Example:

"bitcoin"

network_identifier.network

string

required

If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.

Example:

"mainnet"

network_identifier.sub_network_identifier

object

In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.

Show child attributes

network_identifier.sub_network_identifier.network

string

required

Example:

"shard 1"

network_identifier.sub_network_identifier.metadata

object

Example:

{
  "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}

operations

object[]

required

Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction. Operations are used both to represent on-chain data (Data API) and to construct new transactions (Construction API), creating a standard interface for reading and writing to blockchains.

Show child attributes

operation_identifier

object

required

The operation_identifier uniquely identifies an operation within a transaction.

Show child attributes

operation_identifier.index

integer<int64>

required

The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described.

Required range: x >= 0

Example:

5

operation_identifier.network_index

integer<int64>

Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).

Required range: x >= 0

Example:

0

type

string

required

Type is the network-specific type of the operation. Ensure that any type that can be returned here is also specified in the NetworkOptionsResponse. This can be very useful to downstream consumers that parse all block data.

Example:

"Transfer"

Restrict referenced related_operations to identifier indices < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.

The operation_identifier uniquely identifies an operation within a transaction.

Show child attributes

Required range: x >= 0

Example:

5

Required range: x >= 0

Example:

0

Example:

[{ "index": 1 }, { "index": 2 }]

status

string

Status is the network-specific status of the operation. Status is not defined on the transaction object because blockchains with smart contracts may have transactions that partially apply (some operations are successful and some are not). Blockchains with atomic transactions (all operations succeed or all operations fail) will have the same status for each operation. On-chain operations (operations retrieved in the /block and /block/transaction endpoints) MUST have a populated status field (anything on-chain must have succeeded or failed). However, operations provided during transaction construction (often times called "intent" in the documentation) MUST NOT have a populated status field (operations yet to be included on-chain have not yet succeeded or failed).

Example:

"Reverted"

account

object

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

Show child attributes

account.address

string

required

The address may be a cryptographic public key (or some encoding of it) or a provided username.

Example:

"0x3a065000ab4183c6bf581dc1e55a605455fc6d61"

account.sub_account

object

An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.

Show child attributes

account.sub_account.address

string

required

The SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.

Example:

"0x6b175474e89094c44da98b954eedeac495271d0f"

account.sub_account.metadata

object

If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.

account.metadata

object

Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.

amount

object

Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.

Show child attributes

amount.value

string

required

Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.

Example:

"1238089899992"

amount.currency

object

required

Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).

Show child attributes

amount.currency.symbol

string

required

Canonical symbol associated with a currency.

Example:

"BTC"

amount.currency.decimals

integer<int32>

required

Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.

Required range: x >= 0

Example:

8

amount.currency.metadata

object

Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.

Example:

{ "Issuer": "Satoshi" }

amount.metadata

object

coin_change

object

CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model).

Show child attributes

coin_change.coin_identifier

object

required

CoinIdentifier uniquely identifies a Coin.

Show child attributes

coin_change.coin_identifier.identifier

string

required

Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.

Example:

"0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"

coin_change.coin_action

enum<string>

required

CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.

Available options:

coin_created,

coin_spent

metadata

object

Example:

{
  "asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
  "hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}

metadata

object

public_keys

object[]

PublicKey contains a public key byte array for a particular CurveType encoded in hex. Note that there is no PrivateKey struct as this is NEVER the concern of an implementation.

Show child attributes

hex_bytes

string

required

Hex-encoded public key bytes in the format specified by the CurveType.

curve_type

enum<string>

required

CurveType is the type of cryptographic curve associated with a PublicKey. * secp256k1: SEC compressed - 33 bytes (https://secg.org/sec1-v2.pdf#subsubsection.2.3.3) * secp256r1: SEC compressed - 33 bytes (https://secg.org/sec1-v2.pdf#subsubsection.2.3.3) * edwards25519: y (255-bits) || x-sign-bit (1-bit) - 32 bytes (https://ed25519.cr.yp.to/ed25519-20110926.pdf) * tweedle: 1st pk : Fq.t (32 bytes) || 2nd pk : Fq.t (32 bytes) (https://github.com/CodaProtocol/coda/blob/develop/rfcs/0038-rosetta-construction-api.md#marshal-keys)

Available options:

secp256k1,

secp256r1,

edwards25519,

tweedle

Response

Expected response to a valid request

ConstructionTransactionResponse is returned by /construction/payloads. It contains an unsigned transaction blob (that is usually needed to construct the a network transaction from a collection of signatures) and an array of payloads that must be signed by the caller.

unsigned_transaction

string

required

payloads

object[]

required

SigningPayload is signed by the client with the keypair associated with an AccountIdentifier using the specified SignatureType. SignatureType can be optionally populated if there is a restriction on the signature scheme that can be used to sign the payload.

Show child attributes

hex_bytes

string

required

Hex-encoded string of the payload bytes.

address

string

[DEPRECATED by account_identifier in v1.4.4] The network-specific address of the account that should sign the payload.

account_identifier

object

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

Show child attributes

account_identifier.address

string

required

The address may be a cryptographic public key (or some encoding of it) or a provided username.

Example:

"0x3a065000ab4183c6bf581dc1e55a605455fc6d61"

account_identifier.sub_account

object

Show child attributes

account_identifier.sub_account.address

string

required

The SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.

Example:

"0x6b175474e89094c44da98b954eedeac495271d0f"

account_identifier.sub_account.metadata

object

account_identifier.metadata

object

Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.

signature_type

enum<string>

SignatureType is the type of a cryptographic signature. * ecdsa: r (32-bytes) || s (32-bytes) - 64 bytes * ecdsa_recovery: r (32-bytes) || s (32-bytes) || v (1-byte) - 65 bytes * ed25519: R (32-byte) || s (32-bytes) - 64 bytes * schnorr_1: r (32-bytes) || s (32-bytes) - 64 bytes (schnorr signature implemented by Zilliqa where both r and s are scalars encoded as 32-bytes values, most significant byte first.) * schnorr_poseidon: r (32-bytes) || s (32-bytes) where s = Hash(1st pk || 2nd pk || r) - 64 bytes (schnorr signature w/ Poseidon hash function implemented by O(1) Labs where both r and s are scalars encoded as 32-bytes values, least significant byte first. https://github.com/CodaProtocol/signer-reference/blob/master/schnorr.ml )

Available options:

ecdsa,

ecdsa_recovery,

ed25519,

schnorr_1,

schnorr_poseidon

MESH

Body

Response