Tracing Cross-VM Transfers

Native SUPRA can move between SupraMVM and SupraEVM. A transfer in either direction is called a crossing. This article describes how to find a crossing and follow it to completion.

Security Considerations

Supra does not yet support light clients, so this article assumes that you either trust your RPC provider or query your own RPC node.

A crossing spans more than one block

A crossing is not a single transaction. The sender’s transaction debits the value in one block, and the chain pays it to the recipient in a later block:

The credit is normally in the next block. The chain applies a bounded number of crossings per block, so under load a crossing waits longer, up to roughly a hundred blocks. Until the credit, the crossing exists but the recipient has not been paid.

Because a crossing spans several transactions, it has an identifier of its own, its settlement id. Each event and log that identifies a crossing carries it, and the settlements endpoints in Follow the crossing are keyed by it.

Which route to use

Each route ends with a settlement id, which Follow the crossing takes. An indexer that follows every crossing from events and logs, rather than one crossing at a time, can start at Follow crossings from events and logs.

Route 1: you sent from SupraMVM

Your call to evm_settlement::deposit_to_evm is an ordinary Move transaction. Fetch it and read the settlement id from its SettlementRecorded event. In the examples, <RPC_HOST> is the RPC host with its scheme, such as https://rpc-devnet.supra.com:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/transactions/<your_transaction_hash>' \
     --header 'Accept: application/json'

The event’s type is 0x1::evm_settlement::SettlementRecorded. Its fields are:

Take record_address as the settlement id. It is already in the form the settlements endpoints take.

The events endpoint serves the same event, so you can find your crossings without the transaction hash:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/events/0x1::evm_settlement::SettlementRecorded' \
     --header 'Accept: application/json'

It returns the crossings the chain recorded, not only yours, a page at a time (count and the x-supra-cursor response header), so match on the sender field. Then follow the crossing.

Route 2: you were paid on SupraEVM

You did not sign the transaction that paid you, so you hold no transaction hash of your own. The settlement id is available in two places:

• The credit’s log. The credit that paid you carries the settlement id in its log. See The credit log below.
• The sender. The sender holds the id from the SettlementRecorded event of their deposit_to_evm transaction (Route 1), and can give it to you.

You can also look your crossings up by your address:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/transactions/settlements?address=0x3131313131313131313131313131313131313131&domain=evm&role=recipient' \
     --header 'Accept: application/json'

domain is required, and is move or evm. It is not inferred from the address, because a Move address and a SupraEVM address can share their leading bytes.

The response is a page of crossings, oldest first, each in the shape shown in Follow the crossing. To page, pass count, and pass the x-supra-cursor response header back as the next request’s start, unchanged. The last page is the one without an x-supra-cursor header. A page can hold fewer than count crossings and still not be the last.

If you are a SupraEVM sender whose crossing to SupraMVM was refunded, the refund pays you on SupraEVM like any other credit, so this route applies to it too. It has an id of its own; see A refund is a completed crossing.

The credit log

The credit that pays you is not a transaction anyone sent. It was never signed, never entered a transaction pool and pays no gas. The eth_* methods serve it as a pseudo-transaction with supraTxKind: "settlement", and its receipt carries one log. eth_getLogs and the logs WebSocket subscription serve that log like any other:

To decode the log with an ABI decoder, declare the event:

event NativeCrossingFromMove(bytes32 indexed settlementId, address indexed recipient, uint256 amountQuants);

To find the credits paid to your address, filter on the topic, leave topics[1] open with null, and put your address in topics[2]:

curl --request POST \
     --url '<RPC_HOST>/rpc/v1/eth' \
     --header 'Content-Type: application/json' \
     --data '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{
       "fromBlock":"<from_block>",
       "toBlock":"latest",
       "address":"0x0000000000000000000000000000000053555002",
       "topics":["0xeb92f00ae1449f5ec894595973acc45046a692dc4111e9ae3282ea58fe23624d",
                 null,
                 "0x000000000000000000000000<your_evm_address>"]
     }]}'

To find the credit of a crossing whose settlement id you hold, put the id in topics[1] and leave out topics[2]. fromBlock must be at or above the node’s oldest retained block. A range that starts below it is refused, not shortened. On /rpc/v1/eth the refusal has code -32002 and reports the oldest retained block as error.data.oldestBlock; the x-supra-oldest-block header is on the REST endpoints only.

A node refuses an eth_getLogs request whose block range or result set exceeds its bound with -32005 (see Error codes). The defaults are 1,024 blocks and 10,000 logs and an operator can change them, so a scan from an early block to latest is split into ranges within the bound.

The receipt and the log cover the SupraEVM side only. SupraMVM’s stages of the crossing, and their statuses, come from the settlements endpoint or from the Move events.

Route 3: you sent from SupraEVM

Your transaction called the crossing precompile, and the precompile emitted the crossing log. The call is described under SupraEVM to SupraMVM. eth_getTransactionReceipt returns it among your transaction’s logs:

To decode the log with an ABI decoder, declare the event:

event NativeCrossingToMove(bytes32 indexed settlementId, address indexed sender, bytes32 indexed recipient, uint256 amountQuants);

The settlement id contains the block height and your transaction’s position in its block. eth_call, eth_estimateGas and debug_traceCall run a call as if it were at position 0 in the simulated block, so the settlementId in a simulated crossing log is not the id the crossing gets once your transaction is included. Take the id from the receipt or from eth_getLogs.

To find your crossings without holding each receipt, filter on the topic, leave topics[1] open with null, and put your address in topics[2]:

curl --request POST \
     --url '<RPC_HOST>/rpc/v1/eth' \
     --header 'Content-Type: application/json' \
     --data '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{
       "fromBlock":"<from_block>",
       "toBlock":"latest",
       "address":"0x0000000000000000000000000000000053555002",
       "topics":["0xf54db30b56b0d1ff3aac68b7368ab780b36f8af2e1980cb0c94a355d89fc84aa",
                 null,
                 "0x000000000000000000000000<your_evm_address>"]
     }]}'

To find the log of a crossing whose settlement id you hold, put the id in topics[1] and leave out topics[2]. The same fromBlock and range bounds apply as in Route 2.

The node also lists your crossings by your address:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/transactions/settlements?address=<your_evm_address>&domain=evm&role=sender' \
     --header 'Accept: application/json'

Route 4: you were paid on SupraMVM

The payout is a deposit into your primary SUPRA store, made by the block’s SupraMVM settlement transaction rather than by a transaction anyone sent. The settlement id is available in two places:

• The payout’s event. The settlement transaction that paid you emits InboundSettlementApplied, whose id is the settlement id. See The Move events a crossing emits.
• The sender. The sender holds the id as topics[1] of their crossing log (Route 3), and can give it to you.

You can also look your crossings up by your address, paging as in Route 2:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/transactions/settlements?address=0x2121212121212121212121212121212121212121212121212121212121212121&domain=move&role=recipient' \
     --header 'Accept: application/json'

Follow the crossing

With a settlement id, one request returns every stage of the crossing that the node holds:

curl --request GET \
     --url '<RPC_HOST>/rpc/v4/transactions/settlements/<settlement_id>' \
     --header 'Accept: application/json'

A SupraEVM to SupraMVM crossing that is still waiting to be paid looks like this. It was recorded at height 25, and the node has executed to height 25:

{
  "settlement_id": "0x73757072613a7365766d2d3e6d6f766500000000000000190000000200000000",
  "as_of_height": 25,
  "pending": {
    "sender": {
      "domain": "evm",
      "address": "0x3131313131313131313131313131313131313131"
    },
    "recipient": {
      "domain": "move",
      "address": "0x2121212121212121212121212121212121212121212121212121212121212121"
    },
    "amount": 4200,
    "recorded_at_height": 25
  },
  "stages": [
    {
      "stage": "initiated_on_evm",
      "block_height": 25,
      "transaction_hash": "8a5c2e4f0d1b3a6978c4e2f1d0b9a8c7e6f5d4c3b2a1908f7e6d5c4b3a291807",
      "status": null,
      "amount": 4200,
      "sender": { "domain": "evm", "address": "0x3131313131313131313131313131313131313131" },
      "recipient": {
        "domain": "move",
        "address": "0x2121212121212121212121212121212121212121212121212121212121212121"
      },
      "refund": null
    }
  ]
}

Once SupraMVM has paid it, pending is null and the last stage says what happened:

{
  "settlement_id": "0x73757072613a7365766d2d3e6d6f766500000000000000190000000200000000",
  "as_of_height": 27,
  "pending": null,
  "stages": [
    {
      "stage": "initiated_on_evm",
      "block_height": 25,
      "transaction_hash": "8a5c2e4f0d1b3a6978c4e2f1d0b9a8c7e6f5d4c3b2a1908f7e6d5c4b3a291807",
      "status": null,
      "amount": 4200,
      "sender": { "domain": "evm", "address": "0x3131313131313131313131313131313131313131" },
      "recipient": {
        "domain": "move",
        "address": "0x2121212121212121212121212121212121212121212121212121212121212121"
      },
      "refund": null
    },
    {
      "stage": "applied_on_move",
      "block_height": 26,
      "transaction_hash": "50d7772078f8b295b3c9d55f0065266667ae0ec172b7880533fbd7b96fa99301",
      "status": 0,
      "amount": 4200,
      "sender": { "domain": "evm", "address": "0x3131313131313131313131313131313131313131" },
      "recipient": {
        "domain": "move",
        "address": "0x2121212121212121212121212121212121212121212121212121212121212121"
      },
      "refund": null
    }
  ]
}

A SupraMVM to SupraEVM crossing passes through recorded, credited_on_evm and then cleared, normally in three consecutive blocks.

settlement_id and the addresses are 0x-prefixed, and transaction_hash is not, as elsewhere in this API.

The stages

Each stage names the block and the transaction that produced it. The table lists the fields each stage fills in; the others are null, and amount is 0 where the stage moves no value.

The status codes

status is SupraMVM’s outcome code, on the stages that have one. null means the stage has no outcome code; it does not mean the stage succeeded. The codes come from the evm_settlement Move module:

The module defines two more codes that status never carries. 3 means the settlement moves no value, and the crossing precompile refuses a zero-value crossing. 5 means the recipient is not on the domain the settlement pays out on, and nothing SupraMVM does for a crossing produces it.

2 cannot occur on Mainnet or Testnet. Freezing a primary SUPRA store needs the SUPRA freeze capability, and supra_coin::initialize, the only way a production chain is initialized, destroys that capability at genesis. It can occur only on a chain initialized through the module’s test-only path.

The same codes are the status of the SettlementBurnApplied event, which reports the burn of the SupraEVM’s gas fees for a block (see below). There, 0 means the burn was retired, or that the request was for zero and nothing was retired, 1 means the escrow held less than the burn asked for and nothing was retired, and 4 means the escrow has not been initialized.

A refund is a completed crossing

When SupraMVM cannot pay a SupraEVM to SupraMVM crossing, for example because the escrow holds less than it asks for, it returns the value to the SupraEVM sender instead of failing. The applied_on_move stage then carries a non-zero status and a refund field. The refund field holds the settlement id of the refund, which is a SupraMVM to SupraEVM crossing of its own. Look it up by that id to follow the value back: it is recorded in the same block, then credited_on_evm to the original sender and cleared.

Nothing is lost in a refund, so do not resubmit a refunded crossing. Its value is already on its way back to the sender.

Follow crossings from events and logs

Every stage of a crossing is also visible as an event or a log that carries the settlement id, so an indexer can link both ends of every crossing from events and logs alone, without the settlements endpoints:

The Move events are served by GET /rpc/v4/events/{event_type} and on the transaction that emitted them. The logs are served by eth_getLogs and the logs WebSocket subscription.

The Move events a crossing emits

All of these are module events of 0x1::evm_settlement. Each is served by GET /rpc/v4/events/{event_type} and on the transaction that emitted it, except the two marked as never committed. The node fails any block that carries an InboundSettlementAlreadyProcessed for a credit the block injected, or a SettlementBurnAlreadyApplied that matches a non-zero burn request, so no committed block carries either.

EscrowReleased and EscrowBurned report movements of the escrow and carry no settlement id. To link a payout to its crossing, use InboundSettlementApplied, which the same settlement transaction emits.

The settlement transaction also carries a summary of what it was given. A block listing returns it as a settlement transaction with vm: "move":

• inbound lists each SupraEVM to SupraMVM crossing it applied, with its settlement id, its status and its refund’s id where it has one.
• cleared lists the settlement ids of the records it deleted.
• burn_block_height and burn_amount are the burn it was asked to apply. Whether the burn happened is in the SettlementBurnApplied event’s status, not in the summary.

Heights and pruning

Every answer is as of a height. Each response states, in as_of_height, the height the node had executed to when it answered. A crossing is paid in a later block than the one that recorded it, so a node that is behind reports a crossing as pending when the chain has already paid it. Compare as_of_height with the chain’s height before concluding that a crossing is delayed.

410 and 404 mean different things. For a crossing older than the node’s retained history, the node answers HTTP 410 Gone, with an x-supra-oldest-block header. It cannot tell a crossing that never happened from one that happened and has since been pruned, and 404 would claim the first. If you get a 410, send the request to an archive provider. 410 applies to crossings out of SupraEVM only. A crossing into SupraEVM is identified by a record address that carries no block height, so for one 404 can also mean that the crossing predates the node’s history, or that this node has not executed it yet. For a crossing out of SupraEVM, 404 means that the node holds the relevant history and has no such crossing.