ReferencedPaymentNonexistence

Assertion that a specific payment, agreed upon to be completed by a certain deadline, has not been made. If confirmed, it shows that no transaction meeting the specified criteria (address, amount, reference, source addresses root) was found within the given block range.

This Information can be used, for example, to justify the liquidation of funds locked in a smart contract on Flare networks if a payment is missed.

Supported chains

Network Type	Supported Chains
Mainnet	BTC (Bitcoin), DOGE (Dogecoin), XRP (XRP Ledger)
Testnet	testBTC (Bitcoin Testnet v3), testDOGE, testXRP

Request

Field	Solidity Type	Description
minimalBlockNumber	uint64	The block number to start the search range.
deadlineBlockNumber	uint64	The block number to include as the end of the search range.
deadlineTimestamp	uint64	The timestamp to include as the end of the search range.
destinationAddressHash	bytes32	The standard hash of the address where the payment was expected.
amount	uint256	The required payment amount in minimal units.
standardPaymentReference	bytes32	The standard payment reference associated with the payment. Must not be zero.
checkSourceAddresses	bool	If true, the source addresses root is checked.
sourceAddressesRoot	bytes32	The root of the Merkle tree of the source addresses.

note

Standard Addresses Root is the root of the Merkle tree build on double keccak256 hashes of the all source addresses of the transaction.

Response

Field	Solidity Type	Description
minimalBlockTimestamp	uint64	The timestamp of the block at minimalBlockNumber.
firstOverflowBlockNumber	uint64	The block number of the firstOverflowBlock.
firstOverflowBlockTimestamp	uint64	The timestamp of the firstOverflowBlockNumber.

• firstOverflowBlockNumber: This is the first block with a height greater than deadlineBlockNumber and a timestamp later than deadlineTimestamp.
• The search range includes blocks from minimalBlockNumber (inclusive) to firstOverflowBlockNumber (exclusive).

Verification process

1. Block Confirmation:

   • If the firstOverflowBlock cannot be determined or lacks the required number of confirmations, the request is rejected.
   • The request is also rejected if firstOverflowBlockNumber is less than or equal to minimalBlockNumber.

2. Search Range:

   • The search range includes blocks from minimalBlockNumber to firstOverflowBlockNumber (exclusive).
   • If the verifier does not have complete visibility of all blocks in this range, the request is rejected.

3. Transaction Validation:

   • The request is confirmed if no transaction meeting the specified criteria (address, source addresses root, amount, reference) is found within the specified block range.
   • The criteria and timestamp interpretation are specific to each chain.

The verification process is chain-specific, with details described below.

UTXO chains (Bitcoin and Dogecoin)

Transaction Criteria

• The transaction must not be a coinbase transaction.
• The transaction must include the specified standard payment reference.
• If checkSourceAddresses is set to true, the sourceAddressesRoot of the transaction must match the specified sourceAddressesRoot.
• The sum of all output values sent to the specified address minus the sum of all input values from the same address must be greater or equal to the specified amount.
  • Typically, the sum of input values for the specified address is zero.

Timestamp

• Uses the mediantime of the block.

Account-based chains (XRPL)

Transaction Criteria

• The transaction must be of type Payment and be a Direct XRP payment (sending and receiving XRP).
• The transaction must include the specified standard payment reference.
• If checkSourceAddresses is set to true, the sourceAddressesRoot of the transaction must match the specified sourceAddressesRoot.
• One of the following conditions must hold:
  • The transaction status is SUCCESS (TransactionResult is tesSUCCESS) and the amount received by the specified address is greater or equal to the specified amount.
  • The transaction status is RECEIVER_FAILURE (TransactionResult is one of tecDST_TAG_NEEDED, tecNO_DST, or tecNO_DST_INSUF_XRP, or is tecNO_PERMISSION while the transaction has no DomainID) and the specified address would have received an amount greater or equal to the specified amount if the transaction had succeeded.

Timestamp

• Uses the close_time of the ledger, converted to UNIX time.

Lowest used timestamp

For the lowestUsedTimestamp parameter, the value of minimalBlockTimestamp is used.

Standard payment reference

A standard payment reference is defined as a 32-byte hex string that can be added to a payment transaction, in the same way that a payment reference is attached to a traditional banking transaction.

Bitcoin and Dogecoin

• Uses OP_RETURN to store references.
• A transaction is considered to have a standardPaymentReference defined if it has:
  • Exactly one output UTXO with OP_RETURN script, and
  • The script is of the form OP_RETURN <reference\> or 6a<lengthOfReferenceInHex\><reference\> in hex, where the length of the reference is 32 bytes.
• Then 0x<reference\> is the standardPaymentReference.

An example is the Bitcoin transaction with the ID 53bb7420d146c957ed4f41c5175043503b5e953ed5af0387340f8c2c4949c2e1 in block 578,772 with standardPaymentReference 0xbdaf8a8067dae5b453e0e27bd33521c166ddc5dc481ee993006dcea30e6e2e5b.

XRPL

• Uses the memoData field.
• A transaction has a standardPaymentReference if it has:
  • Exactly one Memo, and
  • The memoData of this field is a hex string that represents a byte sequence of exactly 32 bytes.
• This 32-byte sequence defines the standardPaymentReference.

An example is the transaction with the ID C610A06B5B26A8AF3D24DB7D3D458B8AC46920803B5694FB1FFC0FB7C1857405 in ledger 81,001,656 with standardPaymentReference 0x7274312e312e33322d6275676669782d322d67653135323239372d6469727479.

Finality

Blockchains have varying confirmation depths to consider blocks as final.

Chain	Confirmations required	Confirmation time
Bitcoin	6	≈60 mins
Dogecoin	60	≈60 mins
XRPL	3	≈12 seconds

Contract Interface

For the complete interface definition, see IReferencedPaymentNonexistence.