Transaction Tracking
This document covers the tooling provided in Skip Go for tracking transaction status across multiple chains and bridge hops.
Background
The /v2/tx
endpoints include unified APIs that broadcast transactions and provide insight into the status of transactions and their subsequent cross-chain actions.
You can use the /v2/tx
endpoints to track the progress of a cross-chain transfer or swap in realtime — no matter how many chains or bridges the transfer touches. (For more advanced use cases, the endpoints support tracking multiple distinct transfers initiated in a single transaction).
You can also use it to identify failure cases (e.g. a swap that fails due to slippage, an IBC transfer that fails due to inactive relayers) and determine where the user’s tokens will become available.
For example, if one of your end users initiates a swap that begins with ATOM on Neutron and concludes with JUNO on Juno, you can use the lifecycle tracking to report when the ATOM moves from Neutron to the Hub, when it reaches Osmosis, and when the JUNO finally arrives safely on Juno.
Basics
At a high-level, the transaction tracking works in two stages:
- Inform our tracking engine that you want to track a particular transaction by submitting it to the chain via
/v2/tx/submit
or submitting it to your own Node RPC then calling/v2/tx/track
- Query the transaction status at some regular interval to get updates on it’s progress
Tracking Multiple Independent Routes
You can use the endpoint to track multiple transfers initiated in a single transaction, where the status of transfer i
is given by entry i
in the transfers
array. For example, I could transfer ATOM to the Cosmos Hub and OSMO to Osmosis in a single transaction and track them with transfers[0]
and transfers[1]
respectively.
For a single transfer that has multiple hops (e.g. transferring ATOM to the Cosmos Hub then to Osmosis), you can track the status of each hop using the entries of transfers[i].transfer_sequence
The status endpoint provides a mixture of high-level fields to keep track of the basic progress of your route and low-level fields to provide high visbility into the individual transactions that make up a single transfer.
Important high-level /v2/tx/status
fields
Each entry in the transfers
array corresponds to a single route that may contain many steps, and each entry in transfer_sequence
will contain very detailed information about each step in that route.
But there a few high-level fields in each transfers
entry that you’ll find useful no matter what your route does or what bridges it involves:
state
: The basic status of your route. This lets you report the basic state of the route to the user (e.g. in progress, failed, etc…)STATE_SUBMITTED
: Indicates the transaction has been accepted for tracking but no on chain evidence has been found yet.STATE_ABANDONED
: Tracking has stopped after 30 minutes without progress. There is likely a relayer outage, an undetected out of gas error, or some other problem.STATE_PENDING
: The route is in progress and no errors have occurred yetSTATE_PENDING_ERROR
: The route is in progress and an error has occurred somewhere, but the error is currently propagating, so the user doesn’t have their tokens returned yet. (This state will only occur for protocols that require an acknowledgement on the source chain to process an error. IBC only at this time)STATE_COMPLETED_SUCCESS
: The route has completed successfully and the user has their tokens on the destination (indicated bytransfer_asset_release
)STATE_COMPLETED_ERROR
: The route errored somewhere and the user has their tokens unlocked in one of their wallets. Their tokens are either on the source chain, an intermediate chain, or the destination chain but in the wrong asset. (transfer_asset_release
indicates where the tokens are)
next_blocking_transfer
: Gives the index of the entry intransfer_sequence
that corresponds to the currently propagating transfer that is immediately blocking the release of the user’s tokens —next_blocking_transfer.transfer_sequence_index
(it could be propagating forward or it could be propagating an error ack backward). This lets you tell the user exactly which operation is pending at a given timetransfer_asset_release
: Info about where the users tokens will be released when the route completes. This populates onSTATE_PENDING_ERROR
,STATE_COMPLETED_SUCCESS
, orSTATE_COMPLETED_ERROR
. This lets you tell the user where to recover their funds in the event of a success or failure (If you want to better understand how to predict this or where funds might end up, see Cross-chain Failure Cases)transfer_asset_release.released
: Boolean given whether the funds are currently available (if the state isSTATE_PENDING_ERROR
, this will befalse
)transfer_asset_release.chain_id
: Chain where the assets are released or will be releasedtransfer_asset_release.denom
: Denom of the tokens the user will have
Detailed Info: Usingtransfer_sequence
The transfer_sequence
array consists of TransferEvent
objects, which give detailed information about an individual transfer operation. The object acts as a wrapper around one details object for each bridge we support:
CCTPTransferInfo
IBCTransferInfo
AxelarTransferInfo
HyperlaneTransferInfo
GoFastTransferInfo
Each one contains slightly different data and statuses corresponding to the details of their bridge, but they all contain some standard info:
from_chain_id
to_chain_id
- Transactions and block explorer links for all of the significant events in the transfer (send tx, receive tx, and sometimes acknowledge tx)
- A status field giving the status of the transfer, which can vary based on bridge
IBC Transfer Data
The state
field in the IBCTransferInfo
entries in the transfer_sequence
array have the following meanings:
TRANSFER_UNKNOWN
: The transfer state is unknownTRANSFER_PENDING
- The send packet for the transfer has been committed and the transfer is pendingTRANSFER_PENDING_ERROR
- There has been a problem with the transfer (e.g. the packet has timed out) but the user doesn’t have their funds unlocked yet because the error is still propagatingTRANSFER_RECEIVED
- The transfer packet has been received by the destination chain. It can still fail and revert if it is part of a multi-hop PFM transferTRANSFER_SUCCESS
- The transfer has been successfully completed and will not revertTRANSFER_FAILURE
- The transfer
packet_txs
contain transaction hashes, chain IDs, and block explorer links for up to 4 transactions:
send_tx
: The packet being sent from the source chainreceive_tx
: The packet being received on the destination chaintimeout_tx
: The packet being timed out on the destination chainacknowledge_tx
: The successful or failed acknowledgement of the packet on the source chain
Axelar Transfer Data
When one of the transfers is an Axelar transfer, the transfer_sequence
array will give an axelar_transfer
(AxelarTransferInfo
), instead of an ibc_transfer
, which contains different data because:
- The Skip Go API may utilize send_token or contract_call_with_token (two underlying Axelar protocols) depending on which is cheaper and which is required to execute the user’s intent
- Axelar does not have a notion of packets or acks, like IBC does
- Axelar provides a nice high level UI (Axelarscan) to track the status of their transfers
More precise details about all the fields are below:
type
: an enum ofAXELAR_TRANSFER_SEND_TOKEN
andAXELAR_TRANSFER_CONTRACT_CALL_WITH_TOKEN
which indicate whether the Axelar transfer is a Send Token or a Contract Call With Token transfer respectively.axelar_scan_link
: Gives the link to Axelar’s bridge explorer (which can help track down and unstick transactions)state
field indicates the current state of the Axelar transfer using the following values:AXELAR_TRANSFER_UNKNOWN
- The transfer state is unknownAXELAR_TRANSFER_PENDING_CONFIRMATION
- The transfer has been initiated but is pending confirmation by the Axelar networkAXELAR_TRANSFER_PENDING_RECEIPT
- The transfer has been confirmed by the Axelar network and is pending receipt at the destinationAXELAR_TRANSFER_SUCCESS
- The transfer has been completed successfully and assets have been received at the destinationAXELAR_TRANSFER_FAILURE
- The transfer has failed
txs
field schema depends on thetype
of the transfer- If
type
isAXELAR_TRANSFER_SEND_TOKEN
, there are 3 txs:send_tx
(initiating the transfer)confirm_tx
(confirming the transfer on axelar)execute_tx
(executing the transfer on the destination)
- If
type
isAXELAR_TRANSFER_CONTRACT_CALL_WITH_TOKEN
:send_tx
(initiating the transfer)gas_paid_tx
(paying for the relayer gas on the source chain)approve_tx
(approving the transaction on Axelar - only exists when the destination chain is an EVM chain)confirm_tx
(confirming the transfer on Axelar - only exists when destination chain is a Cosmos chain)execute_tx
(executing the transfer on the destination)
- If
CCTP Transfer Data
When one of the transfers is a CCTP transfer, the transfer_sequence
array will give a cctp_transfer
(CCTPTransferInfo
), instead of an ibc_transfer
, which contains different data because:
- CCTP works by Circle attesting to & signing off on transfers
- There’s no notion of an acknowledgement in CCTP
More precise details about the different/new fields are below:
state
gives the status of the CCTP transfer:CCTP_TRANSFER_UNKNOWN
- Unknown errorCCTP_TRANSFER_SENT
- The burn transaction on the source chain has executedCCTP_TRANSFER_PENDING_CONFIRMATION
- CCTP transfer is pending confirmation by the cctp attestation apiCCTP_TRANSFER_CONFIRMED
- CCTP transfer has been confirmed by the cctp attestation api but not yet received on the destination chainCCTP_TRANSFER_RECEIVED
- CCTP transfer has been received at the destination chain
txs
contains the chain IDs, block explorer links, and hashes for two transactions:send_tx
: The transaction submitted the CCTP burn action on the source chain to initiate the transferreceive_tx
: The transaction on the destination chain where the user receives their funds
Hyperlane Transfer Data
When one of the transfers is a Hyperlane transfer, the transfer_sequence
array will give a hyperlane_transfer
(HyperlaneTransferInfo
), instead of an ibc_transfer
, which contains different data because:
- Hyperlane is a very flexible protocol where the notion of “approving/verifying” the transfer is undefined / up to the bridge developer to implement
- There’s no notion of an acknowledgement in Hyperlane
More precise details about the different/new fields are below:
state
gives the status of the Hyperlane transfer:HYPERLANE_TRANSFER_UNKNOWN
- Unknown errorHYPERLANE_TRANSFER_SENT
- The Hyperlane transfer transaction on the source chain has executedHYPERLANE_TRANSFER_FAILED
- The Hyperlane transfer failedHYPERLANE_TRANSFER_RECEIVED
- The Hyperlane transfer has been received at the destination chain
txs
contains the chain IDs, block explorer links, and hashes for two transactions:send_tx
: The transaction submitted the CCTP burn action on the source chain to initiate the transferreceive_tx
: The transaction on the destination chain where the user receives their funds
OPInit Transfer Data
When one of the transfers is a OPInit transfer, the transfer_sequence
array will give a op_init_transfer
(OPInitTransferInfo
), instead of an ibc_transfer
, which contains different data because:
- The OPInit bridge is the Initia ecosystem’s native bridging solution facilitating transfers between Initia and the Minitias.
- There’s no notion of an acknowledgement in the OPInit bridge
More precise details about the different/new fields are below:
state
gives the status of the OPInit transfer:OPINIT_TRANSFER_UNKNOWN
- Unknown errorOPINIT_TRANSFER_SENT
- The deposit transaction on the source chain has executedOPINIT_TRANSFER_RECEIVED
- OPInit transfer has been received at the destination chain
txs
contains the chain IDs, block explorer links, and hashes for two transactions:send_tx
: The transaction that submitted the OPInit deposit action on the source chain to initiate the transferreceive_tx
: The transaction on the destination chain where the user receives their funds
Go Fast Transfer Data
When one of the transfers is a GoFastTransfer
, the transfer_sequence
array will include a go_fast_transfer
(GoFastTransferInfo
). This field includes specific information about user-initiated intents and solver fulfillments, which require specific data fields to track the transfer process.
Below are detailed explanations of the different fields and their purposes:
fromChainID
: The chain ID where the transfer originates (source chain).toChainID
: The chain ID where the assets are being sent (destination chain).state
: Indicates the current status of the transfer. Possible values are:GO_FAST_TRANSFER_UNKNOWN
: An unknown error has occurred.GO_FAST_TRANSFER_SENT
: The user’s intent has been successfully submitted on the source chain.GO_FAST_POST_ACTION_FAILED
: The transfer failed after the initial intent submission.GO_FAST_TRANSFER_TIMEOUT
: The transfer did not complete within the expected time frame.GO_FAST_TRANSFER_FILLED
: The transfer was successfully fulfilled on the destination chain.GO_FAST_TRANSFER_REFUNDED
: The user’s assets have been refunded on the source chain.
txs
: Contains transaction details related to the GoFast transfer:orderSubmittedTx
: The transaction where the user called initiateIntent on the source chain.orderFilledTx
: The transaction where the solver called fulfill on the destination chain.orderRefundedTx
: The transaction where the user received a refund on the source chain, if applicable.orderTimeoutTx
: The transaction indicating a timeout occurred in the transfer process.
When tracking a Go Fast transfer, you can use the GoFastTransferInfo
to monitor the progress and status of your asset transfer between chains. For instance, if the state is GO_FAST_TRANSFER_FILLED
, you know that the transfer was successful and your assets should be available on the destination chain. If the state is GO_FAST_TRANSFER_TIMEOUT
, you can check the orderTimeoutTx
for details on the timeout event.
The Go Fast Protocol involves interactions with solvers who fulfill transfer intents. The additional transaction fields help provide transparency and traceability throughout the transfer process, ensuring users can track each step and identify any issues that may arise.
Detailed Example of Typical Usage
This will walk through an example of how a developer would use the api to track the progress of a route that may include multiple
In this particular example, we’ll cover a simple 2-hop IBC transfer from axelar to the cosmoshub through osmosis.
Usage is similar for tracking Axelar transfers or transfers that include multiple hops over distinct bridges but the data structures change slightly depending on what underlying bridge is being used
1. Call /tx/submit
to broadcast a transaction
Post a signed user transaction (that you can form using /fungible
endpoints) to the /submit
endpoint. The Skip Go API will handle the broadcasting of this transaction and asynchronously begin tracking the status of this transaction and any subsequent transfers.
A successful response looks like the following:
It indicates that the transaction was accepted by the Skip Go API and its status can be tracked using the returned tx_hash
.
The transaction is broadcast using BROADCAST_MODE_SYNC
and in the event that a transaction is rejected by the node, the /submit
endpoint will return a 400 response along with the failure reason as shown below:
Tracking a transaction that was not broadcast using /submit
If a transaction was not broadcast through the /submit
endpoint and has already landed on chain, the /track
endpoint can be used to initiate tracking of the transaction’s progress.
2. Call /status
to query the status of the transaction and IBC transfer progress
Skip Go API continually indexes chain state to determine the state of the transaction and the subsequent IBC transfer progress. This information can be queried using the /status
endpoint.
It will initially yield a response that looks like the following:
- There’s a top-level
transfers
field, which gives an array where each entry corresponds to a single sequence of transfers. This does not mean there’s one entry in thetransfers
field for every bridging operation. In general, onetransfer
could consist of an arbitrarily long sequence of swaps and transfers over potentially multiple bridges.transfers
is an array because one transaction can initiate potentially several distinct and independent transfers (e.g. transferring OSMO to Osmosis and ATOM to the Hub) in the same tx. - The
state
field will giveSTATE_SUBMITTED
indicating the transaction has been accepted for tracking by the Skip Go API but no events have been indexed yet:
Once indexing for the transaction has begun, the state
will change to STATE_PENDING
.
- The status of any transfers along the transfer sequence will be returned in the
transfer_sequence
field as shown in the example response below. - The entries in the
transfer_sequence
correspond to transfers and will be represented by different objects depending on which bridge is being used (e.g. Axelar or IBC). - The
next_blocking_transfer
field gives some information about the next blocking transfer in thetransfer_sequence
field.- The
transfer_sequence_index
indicates which transfer in thetransfer_sequence
field is blocking progress.
- The
- The
transfer_asset_release
field will be populated with information about the asset release as it is becomes known.- The
chain_id
anddenom
fields indicate the location and asset being released. - The
released
field indicates whether the assets are accessible. Thetransfer_asset_release
field may become populated in advance of asset release if it can be determined with certainty where the eventual release will be. This will happen for example in a transfer sequence that is a PFM-enabled sequence of IBC transfers when one hop fails due to packet timeout or an acknowledgement failure. The transfer sequence will revert and thetransfer_asset_release
field will indicate that the assets will be released on the initial chain.
- The
The transfer assets will be released before all expected acknowledgements have been indexed. When the transfer sequence has reached this state, the status
will be updated to STATE_RECEIVED
as shown in the example response below. Note that transfer_asset_release
now indicates the chain ID of the chain where the assets are released and the denomination of the released assets.
Once it has been determined that all packets along the transfer sequence have either been acknowledged or timed out, state
will be updated to STATE_COMPLETED_SUCCESS
as shown in the example response below. Note that next_blocking_transfer
is now null since the transfer is complete.
Any packet acknowledgement errors will be surfaced in the error field for the relevant packet as follows:
Any execution errors for the initial transaction will be surfaced in the error field at the top level of the response as follows: