Taker Events
The atomic swap process goes through a series of steps to perform and confirm transactions, then release funds accordingly. If a swap fails, the taker payment will be returned to the taker's address (minus network transaction fees). Sometimes failed swaps were due to a taker or maker going offline in the middle of a swap, so Swap Watcher seednodes were created to process certain events on behalf of the maker/taker.
Swap watchers act to complete a swap or refund if one or both sides go offline for too long. This is done in a non-custodial manner, and funds are still governed by HTLC which can only be released to either the maker or the taker's address, and only after specific conditions are met, such as completion on the side that is online and/or a timeout.
Takers send all the necessary information to watch the swap on taker/maker chains together with two signed transactions to watchers: one to spend the maker payment (maker payment spend) and the other to refund the taker payment (taker payment refund). If the maker proceeds with the swap and spends the taker payment (and therefore exposes the secret), and the taker doesn't respond for a duration, the watcher sends the maker payment spend transaction to the chain on behalf of the taker (after appending the secret to the redeem script). If the taker sends the taker payment but the maker doesn't spend it, and the taker doesn't send the refund transaction for a duration, then the watchers complete the process by sending the taker payment refund transaction to the chain.
Click on an Event below to view its structure:
- Started
- Negotiated
- TakerFeeSent
- TakerPaymentInstructionsReceived
- MakerPaymentReceived
- MakerPaymentWaitConfirmStarted
- MakerPaymentValidatedAndConfirmed
- TakerPaymentSent
- TakerPaymentSpent
- MakerPaymentSpent
- MakerPaymentSpendConfirmed
- MakerPaymentSpentByWatcher
- Finished
Click on an Event below to view its structure:
-
The
Startedevent indicates that mandatory pre-checks, such as "available balance," passed and the swap started successfully.The swap goes to negotiation stage after this event occurs.
Parameter* = required Type Description lock_duration* number (integer)the lock duration of swap payments in seconds. The sender can refund the transaction when the lock duration is passed. The taker payment is locked for the lock duration. The maker payment is locked for lock duration * 2 maker* string (hexadecimal)the p2p ID of maker node maker_amount* string (numeric)the amount of coins to be swapped by maker maker_coin* stringthe ticker of the maker coin maker_coin_start_block* number (integer)the maker coin block number at the start of the swap maker_payment_confirmations* number (integer)the required number of blockchain confirmations for maker payment started_at* number (UTC timestamp in seconds)the timestamp at the start of the swap taker_amount* string (numeric)the amount of coins to be swapped by taker taker_coin* stringthe ticker of the taker coin taker_coin_start_block* number (integer)the taker coin block number at the start of the swap taker_payment_confirmations* number (integer)the required number of blockchain confirmations for taker payment taker_payment_lock* number (UTC timestamp in seconds)the taker payment is locked until this timestamp uuid* stringthe swap uuid maker_payment_requires_nota boolOptional. whether dPoW notarization is required for maker payment; can be null; available since beta-2.0.1738taker_payment_requires_nota boolOptional. whether dPoW notarization is required for taker payment; can be null; available since beta-2.0.1738
The StartFailed event indicates that some of the pre-checks did not pass, and therefore the swap did not start.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The Negotiated event indicates that taker has received and validated swap negotiation data from maker.
Taker generates taker fee transaction after this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| maker_payment_locktime* | number (UTC timestamp in seconds) | the maker payment is locked until this timestamp |
| maker_pubkey* | string (hexadecimal) | a persistent secp256k1 public key of maker node |
The NegotiateFailed event indicates that maker negotiation data was not received or did not pass validation.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerFeeSent event indicates that taker has broadcast the dex fee transaction.
Taker starts waiting for maker payment after this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The TakerFeeSendFailed event indicates that the taker dex fee transaction failed to broadcast to the taker coin blockchain, or that the taker failed to send the transaction data to maker.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerPaymentInstructionsReceived event indicates that the taker has received payment instructions.
This event does not have additional data.
The MakerPaymentValidateFailed event indicates that taker was not able to receive or validate the maker payment transaction.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The MakerPaymentReceived event indicates that taker received the maker payment transaction data.
Taker starts waiting for transaction confirmation after this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The MakerPaymentWaitConfirmStarted event indicates that taker started waiting for maker payment confirmation.
This event does not have additional data.
The MakerPaymentWaitConfirmFailed event indicates that the maker payment transaction did not reach the required number of confirmations before the internal timeout expiration.
Taker swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The MakerPaymentValidatedAndConfirmed event indicates that taker validated maker payment and the payment was confirmed the required number of times.
Taker sends his payment after this event occurs.
This event does not have additional data.
The TakerPaymentSent event indicates that taker broadcast taker payment transaction to taker coin blockchain.
Taker starts waiting for maker to spend this transaction.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The TakerPaymentTransactionFailed event indicates that taker failed to broadcast transaction to taker coin blockchain.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerPaymentWaitConfirmFailed event indicates that the taker payment transaction did not reach the required number of confirmations before the internal timeout expiration.
When this event occurs taker starts waiting for taker payment lock time expiration to issue a refund.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerPaymentDataSendFailed event indicates that taker was not able to send his payment data to maker due to a network error.
When this event occurs taker starts waiting for taker payment lock time expiration to issue a refund.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerPaymentSpent event indicates that maker spent taker payment and taker discovered the transaction.
When this event occurs taker extracts the secret from the transaction and attempts to spend maker payment.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The TakerPaymentWaitForSpendFailed event indicates that maker did not spend taker payment before lock time expiration.
When this event occurs taker attempts to refund the payment.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The MakerPaymentSpendFailed event indicates that taker failed to broadcast maker payment spend transaction to the maker coin blockchain.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The MakerPaymentSpent event indicates that taker spent maker payment.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The MakerPaymentSpendConfirmed event indicates that the broadcasted tx for taker spending maker payment was not reverted.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The MakerPaymentSpendConfirmFailed event indicates that the broadcasted tx for taker spending maker payment was not reverted.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The MakerPaymentSpentByWatcher event indicates that the maker payment has been released to the taker while the taker was offline.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
TakerPaymentWaitRefundStarted event indicates that taker started waiting for lock time expiration to refund the payment.
| Parameter* = required | Type | Description |
|---|---|---|
| wait_until* | number (UTC timestamp) | the timestamp at which a refund will occur |
TakerPaymentRefundStarted event indicates that taker was has initiated the refund process.
The TakerPaymentRefundedByWatcher is fired if the watcher refunded the taker payment for the taker while the taker is offline.
It will be shown in the swap status when the taker runs the defi framework again after being offline (if the watcher refunded the swap during the time the taker was offline).
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
TakerPaymentRefundFailed event indicates that taker was not able to broadcast a refund transaction to taker coin blockchain.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| error* | string | error description with stack trace |
The TakerPaymentRefunded event indicates that taker broadcast the taker payment refund transaction.
The swap finishes immediately when this event occurs.
| Parameter* = required | Type | Description |
|---|---|---|
| tx_hash* | string | the hash of the transaction |
| tx_hex* | string | transaction bytes in hexadecimal format |
The TakerPaymentRefundFinished event indicates that taker refund process is complete.
The swap finishes immediately when this event occurs. This event does not have additional data.
The Finished event indicates that the swap finished.
This event does not have additional data.