What is an address sequence?

An address sequence (also known as an address nonce) is a unique number used only once in order to stop replay attacks on the network.

What is a replay attack? This would be when a malicious entity would rebroadcast a user's transaction to gain an advantage. Imagine if Alice sent Bob 1 ETH in a transaction that Alice signed. Once this transaction was successful then Bob would receive 1 ETH. If Bob could then rebroadcast the same signed transaction onto the blockchain, to get another 1 ETH from Alice, then this would be a replay attack.

To stop this replay attack possibility every time Alice creates a transaction, Alice also includes a sequence/nonce number. The blockchain nodes will then only process a transaction from Alice with a particular sequence number once.

In some blockchain technologies, e.g. Ethereum, the sequence number is equal to the number of transactions that a user has currently sent. So the user will start with a sequence number of 0, then 1, then 2, etc. In other technologies, this is not always the case, e.g. in the XRP ledger, where a user will nowadays (after the DeleteableAccounts amendment) start with the sequence number equal to the block number where the user first received XRP.

Either way, this guide covers how to get the address sequence/nonce from an Overledger API.

📘

Address sequence information is not available in UTXO-based DLTs (Bitcoin, Corda,...) as UTXO DLTs do not need this method of replay protection.

Prerequisites

• Create an account and generate your application's API keys
  Create an account on Quant Connect. Then, register your application to generate API keys to authorise your requests on Overledger APIs.

• Obtain an authorization token
  You must obtain an authorisation token to interact with Overledger's API and call any endpoint. This token will authenticate your requests and grant you access to the necessary endpoints. Please follow the authentication process provided by Overledger to get your authorisation token.

Call the endpoint

This endpoint provides the current sequence number for transactions for the specified address.

Replace <address> with the address whose sequence number is to be determined:

/v2/autoexecution/search/address/sequence/<address>

For example, to get the sequence number of address 0x68cb826D4f8960b2c51025bE03798691ED0Ce4E7.

In the request body, pass the technology and network for which you would like to determine the sequence number and add the addressId as a path parameter then send the request.

curl --request POST \
     --url https://api.sandbox.overledger.io/v2/autoexecution/search/address/sequence/0x68cb826D4f8960b2c51025bE03798691ED0Ce4E7 \
     --header 'Authorization: Bearer token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "location": {
    "technology": "ethereum",
    "network": "ethereum sepolia testnet"
  }
}
'

If the request is successful, you would receive a response with the address sequence as shown below:

{
    "preparationAddressSequenceSearchResponse": {
        "requestId": "bf37ac27-3f94-45eb-9397-351250289deb",
        "gatewayFee": {
            "amount": "0",
            "unit": "QNT"
        }
    },
    "executionAddressSequenceSearchResponse": {
        "location": {
            "technology": "Ethereum",
            "network": "ethereum sepolia testnet"
        },
        "sequence": "0",
        "timestamp": "1710168984",
        "addressId": "0x68cb826D4f8960b2c51025bE03798691ED0Ce4E7"
    }
}

In the response above, sequence provides the value, which is 0 for address 0x68cb826D4f8960b2c51025bE03798691ED0Ce4E7.