Transaction Format
Describes the format of signed and unsigned transactions in Substrate.
This article describes in detail the data structure of signed and unsigned transactions in Substrate. This is particularly useful for understanding how the transaction pool checks incoming transactions. Parachain builders will find this useful for customizing how their transactions are formatted as well as writing client applications that need to adhere to a chosen format.
Extrinsics normally contain a signature, some data to describe if the extrinsic has passed some validity checks and a reference to the pallet and call that it is intended for. This format provides a way for applications to ensure the requirements for an extrinsic are met and correctly constructed.
Unchecked: signed transactions that require some validation check before they can be accepted in the transaction pool. Any unchecked extrinsic contains the signature for the data being sent plus some extra data.
Checked: inherent extrinsics which by definition don't require signature verification. Instead, they carry information on where the extrinsic comes from and some extra data.
Opaque: used for cases when an extrinsic hasn't yet been committed to a format but can still be decoded.
Extra data can be any additional information that would be useful to attach to a transaction or inherent. For example, the nonce of the transaction, the tip for the block author, or how long the extrinsic is valid for. This information is provided by a specialized extensions that help determine the validity and ordering of extrinsics before they get included in a block.
A signed transaction might be constructed like so:
How transactions are constructed
Substrate defines its transaction formats generically to allow developers to implement custom ways to define valid transactions. In a runtime built with FRAME however (assuming transaction version 4), a transaction must be constructed by submitting the following encoded data:
<signing account ID> + <signature> + <additional data>
When submitting a signed transaction, the signature is constructed by signing:
The actual call, composed of:
The index of the pallet.
The index of the function call in the pallet.
The parameters required by the function call being targeted.
Some extra information, verified by the signed extensions of the transaction:
What's the era for this transaction, i.e. how long should this call last in the transaction pool before it gets discarded?
The nonce, i.e. how many prior transactions have occurred from this account? This helps protect against replay attacks or accidental double-submissions.
The tip amount paid to the block producer to help incentive it to include this transaction in the block.
Then, some additional data that's not part of what gets signed is required, which includes:
The spec version and the transaction version. This ensures the transaction is being submitted to a compatible runtime.
The genesis hash. This ensures that the transaction is valid for the correct chain.
The block hash. This corresponds to the hash of the checkpoint block, which enables the signature to verify that the transaction doesn't execute on the wrong fork, by checking against the block number provided by the era information.
The SCALE encoded data is then signed (i.e. (call
, extra
, additional
)) and the signature, extra data and call data is attached in the correct order and SCALE encoded, ready to send off to a node that will verify the signed payload. If the payload to be signed is longer than 256 bytes, it is hashed just prior to being signed, to ensure that the size of the signed data does not grow beyond a certain size.
This process can be broken down into the following steps:
Construct the unsigned payload.
Create a signing payload.
Sign the payload.
Serialize the signed payload.
Submit the serialized transaction.
An extrinsic is encoded into the following sequence of bytes just prior to being hex encoded:
[ 1 ] + [ 2 ] + [ 3 ] + [ 4 ]
where:
[1]
contains the compact encoded length in bytes of all of the following data. Learn how compact encoding works using SCALE.[2]
is au8
containing 1 byte to indicate whether the transaction is signed or unsigned (1 bit), and the encoded transaction version ID (7 bits).[3]
if a signature is present, this field contains an account ID, an SR25519 signature and some extra data. If unsigned this field contains 0 bytes.[4]
is the encoded call data. This comprises of 1 byte denoting the pallet to call into, 1 byte denoting the call to make in that pallet, and then as many bytes as needed to encode the arguments expected by that call.
The way applications know how to construct a transaction correctly is provided by the metadata interface. An application will know how to correctly encode a transaction by using the metadata types and transaction format. If a call doesn't need to be signed, then the first bit in [2]
will be 0 and so an application will know not to try decoding a signature.
Polkadot JS Apps example:
Here we demonstrate a detailed, manual extrinsic construction and submission of a balance transfer from Bob to Dave: Bob sends 42 UNIT
s to Dave.
Start a node template in
--dev
mode (see the quick start guide for how to set this up)Set
Bob
as sender and selectbalances
pallet and thetransfer(dest, value)
callSet
MultiAddress
toId
and theAccountID
toDave
for thedest
Set
value
to42000000000000
(this is42 UNIT
as defined in the chain spec of the node template)Click
Submit Transaction
button (lower right) and un-check sign and submit to generate a signed transaction with the defaultnonce = 0
andLifetime = 64
for inspection
Encoded call data:
0x050300306721211d5404bd9da88e0204360a1a9ab8b87c66c1bc2fcdd37f3c2222cc200b00a014e33226
Encoded call hash:
0x26c333c22ec93ac431ee348168530b7d77e85d766f130af60890c0fd6ab20d5b
Resulting signed transaction call hash:
0x450284008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48018eeaeb6a3496444c08b5c3e10e0c5f94776774591504ef4ef26e3873799831285a1a7cbd8ba2babe6fba94ea3585bf20e46c80ce7baeb25b149529ece931478c45020c00050000306721211d5404bd9da88e0204360a1a9ab8b87c66c1bc2fcdd37f3c2222cc200b00a014e33226
Here you can Copy the Signed transaction
data to submit via RPC directly, or for inspection on the Developer
-> Extrinsics
-> Decode
section. We will use this window now to submit the transaction and watch the result.
Close the
authorize transaction
cardClick
Submit Transaction
button (lower right) and keep sign and submit checkedNavigate to the
Developer
->RPC Calls
tab
In the RPC tab, you should see the result of your author_submitAndWatchExtrinsic
call as something similar to:
Navigate to the
Network
->Explorer
tabOpen the
balances.Transfer
extrinsic details by clicking the<block number>-<extrinsic number>
in the top right of the cardInspect the on-chain details of your transaction
Click the #/extrinsics/decode/0x....
link to open the decoded details of the above Signed transaction
data and notice it is identical to what we submitted. Thus before or after submitting an extrinsic, this tool can be used to decode and introspect transaction call data.
Signed extensions
Substrate provides the concept of signed extensions to extend an extrinsic with additional data, provided by the SignedExtension
trait.
The transaction queue regularly calls signed extensions to keep checking that a transaction is valid before it gets put in the ready queue. This is a useful safeguard for verifying that transactions won't fail in a block. They are commonly used to enforce validation logic to protect the transaction pool from spam and replay attacks.
In FRAME, a signed extension can hold any of the following types by default:
AccountId
: to encode the sender's identity.Call
: to encode the pallet call to be dispatched. This data is used to calculate transaction fees.AdditionalSigned
: to handle any additional data to go into the signed payload. This makes it possible to attach any custom logic prior to dispatching a transaction.Pre
: to encode the information that can be passed from before a call is dispatch to after it gets dispatched.
FRAME's system pallet provides a set of useful SignedExtensions
out of the box.
Practical examples
An important signed extension for validating transactions is CheckSpecVersion
.
It provides a way for the sender to provide the spec version as a signed payload attached to the transaction. Since the spec version is already known in the runtime, the signed extension can perform a simple check to verify that the spec versions match. If they don't, the transaction fail before it gets put in the transaction pool.
Other examples include the signed extensions used to calculate transaction priority. These are:
CheckWeight
: sets the value for priority to0
for all dispatch classes.ChargeTransactionPayment
: calculates the overall priority, modifying the priority value accordingly.
The priority depends on the dispatch class and the amount of tip-per-weight or tip-per-length (whatever is more limiting) the sender is willing to pay. Transactions without a tip use a minimal tip value of 1
for priority calculations to make sure that not all transactions end up having a priority of 0
. The consequence of this is that smaller transactions are preferred over larger ones.
Where to go next
Now that you have seen how transactions are constructed, you might want to review how they progress from the transaction pool to the runtime and get added to blocks or how to use tools that enable you to submit transactions offline or using a REST API.
tx-wrapper for offline transactions
sidecar for REST-based transactions
Last updated