Construction
Derive returns the AccountIdentifier associated with a public key. Blockchains that require an on-chain action to create an account should not implement this method.
ConstructionDeriveRequest is passed to the /construction/derive endpoint. Network is provided in the request because some blockchains have different address formats for different networks. Metadata is provided in the request because some blockchains allow for multiple address types (i.e. different address for validators vs normal accounts).
POST /construction/derive HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 344
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"public_key": {
"hex_bytes": "text",
"curve_type": "secp256k1"
},
"metadata": {
"staking_credential": {
"hex_bytes": "text",
"curve_type": "secp256k1"
},
"address_type": "text"
}
}{
"address": "text",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"metadata": {}
}Preprocess is called prior to /construction/payloads to construct a request for any metadata that is needed for transaction construction given (i.e. account nonce). The options object returned from this endpoint will be sent to the /construction/metadata endpoint UNMODIFIED by the caller (in an offline execution environment). If your Construction API implementation has configuration options, they MUST be specified in the /construction/preprocess request (in the metadata field).
ConstructionPreprocessRequest is passed to the /construction/preprocess endpoint so that a Rosetta implementation can determine which metadata it needs to request for construction. Metadata provided in this object should NEVER be a product of live data (i.e. the caller must follow some network-specific data fetching strategy outside of the Construction API to populate required Metadata). If live data is required for construction, it MUST be fetched in the call to /construction/metadata. The caller can provide a max fee they are willing to pay for a transaction. This is an array in the case fees must be paid in multiple currencies. The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided).
POST /construction/preprocess HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1719
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": null
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"staking_credential": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"payment_key": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"metadata": {
"relative_ttl": 1,
"deposit_parameters": {
"keyDeposit": "text",
"poolDeposit": "text"
}
},
"max_fee": [
{
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": null
},
"metadata": {}
}
],
"suggested_fee_multiplier": 1
}{
"options": {
"relative_ttl": 1,
"transaction_size": 1
},
"required_public_keys": [
{
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
}
]
}Get any information required to construct a transaction for a specific network. Metadata returned here could be a recent hash to use, an account sequence number, or even arbitrary chain state. The request used when calling this endpoint is created by calling /construction/preprocess in an offline environment. You should NEVER assume that the request sent to this endpoint will be created by the caller or populated with any custom parameters. This must occur in /construction/preprocess. It is important to clarify that this endpoint should not pre-construct any transactions for the client (this should happen in /construction/payloads). This endpoint is left purposely unstructured because of the wide scope of metadata that could be required.
A ConstructionMetadataRequest is utilized to get information required to construct a transaction. The Options object used to specify which metadata to return is left purposely unstructured to allow flexibility for implementers. Options is not required in the case that there is network-wide metadata of interest. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.
POST /construction/metadata HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 295
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"options": {
"relative_ttl": 1,
"transaction_size": 1
},
"public_keys": [
{
"hex_bytes": "text",
"curve_type": "secp256k1"
}
]
}{
"metadata": {
"account_sequence": 23,
"recent_block_hash": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
},
"suggested_fee": [
{
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": null
},
"metadata": {}
}
]
}Payloads is called with an array of operations and the response from /construction/metadata. It returns an unsigned transaction blob and a collection of payloads that must be signed by particular AccountIdentifiers using a certain SignatureType. The array of operations provided in transaction construction often times can not specify all "effects" of a transaction (consider invoked transactions in Ethereum). However, they can deterministically specify the "intent" of the transaction, which is sufficient for construction. For this reason, parsing the corresponding transaction in the Data API (when it lands on chain) will contain a superset of whatever operations were provided during construction.
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.
POST /construction/payloads HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1794
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": null
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"staking_credential": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"payment_key": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"metadata": {
"ttl": "text",
"protocol_parameters": {
"coinsPerUtxoSize": "text",
"maxTxSize": 1,
"maxValSize": 1,
"keyDeposit": "text",
"maxCollateralInputs": 1,
"minFeeCoefficient": 1,
"minFeeConstant": 1,
"minPoolCost": "text",
"poolDeposit": "text",
"protocol": 1
}
},
"public_keys": [
{
"hex_bytes": "text",
"curve_type": "secp256k1"
}
]
}{
"unsigned_transaction": "text",
"payloads": [
{
"address": "text",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"hex_bytes": "text",
"signature_type": "ecdsa"
}
]
}Combine creates a network-specific transaction from an unsigned transaction and an array of provided signatures. The signed transaction returned from this method will be sent to the /construction/submit endpoint by the caller.
ConstructionCombineRequest is the input to the /construction/combine endpoint. It contains the unsigned transaction blob returned by /construction/payloads and all required signatures to create a network transaction.
POST /construction/combine HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 610
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"unsigned_transaction": "text",
"signatures": [
{
"signing_payload": {
"address": "text",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"hex_bytes": "text",
"signature_type": "ecdsa"
},
"public_key": {
"hex_bytes": "text",
"curve_type": "secp256k1"
},
"signature_type": "ecdsa",
"hex_bytes": "text"
}
]
}{
"signed_transaction": "text"
}Parse is called on both unsigned and signed transactions to understand the intent of the formulated transaction. This is run as a sanity check before signing (after /construction/payloads) and before broadcast (after /construction/combine).
ConstructionParseRequest is the input to the /construction/parse endpoint. It allows the caller to parse either an unsigned or signed transaction.
Signed is a boolean indicating whether the transaction is signed.
This must be either the unsigned transaction blob returned by /construction/payloads or the signed transaction blob returned by /construction/combine.
POST /construction/parse HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 218
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed": true,
"transaction": "text"
}{
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": null
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"staking_credential": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"payment_key": {
"hex_bytes": "1B400D60AAF34EAF6DCBAB9BBA46001A23497886CF11066F7846933D30E5AD3F",
"curve_type": "edwards25519"
},
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"signers": [
"text"
],
"account_identifier_signers": [
{
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {
"chain_code": "text"
}
}
],
"metadata": {}
}TransactionHash returns the network-specific transaction hash for a signed transaction.
ConstructionHashRequest is the input to the /construction/hash endpoint.
POST /construction/hash HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 211
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed_transaction": "text"
}{
"transaction_identifier": {
"hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
},
"metadata": {}
}Submit a pre-signed transaction to the node. This call should not block on the transaction being included in a block. Rather, it should return immediately with an indication of whether or not the transaction was included in the mempool. The transaction submission response should only return a 200 status if the submitted transaction could be included in the mempool. Otherwise, it should return an error.
The transaction submission request includes a signed transaction.
POST /construction/submit HTTP/1.1
Host: ada.nownodes.io
api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 211
{
"network_identifier": {
"blockchain": "cardano",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed_transaction": "text"
}{
"transaction_identifier": {
"hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
},
"metadata": {}
}