Show / Hide Table of Contents

Class LedgerSettlingFacilitator

Production-quality x402 facilitator that decodes a signed XRPL transaction blob, checks it against the accepted requirement, submits it to the ledger, waits for a validated outcome and checks what the ledger actually delivered.

Inheritance
object
LedgerSettlingFacilitator
Implements
IX402Facilitator
Namespace: Xrpl.X402.AspNetCore
Assembly: Xrpl.X402.AspNetCore.dll
Syntax
public sealed class LedgerSettlingFacilitator : IX402Facilitator
Remarks

Before submitting, the blob must be a Payment to PayTo (with the destination tag an X-address or extra.destinationTag names) of exactly Amount in Asset (and extra.issuer for an issued currency), without tfPartialPayment, bound to extra.invoiceId when there is one, with a LastLedgerSequence that has not passed and does not reach further than the requirement's timeout allows. After validation, the metadata's delivered_amount must cover the requirement. Each refusal has its own ErrorReason: invalid_transaction_type, invalid_destination, invalid_partial_payment, invalid_asset, invalid_amount, invalid_invoice_id, invalid_last_ledger_sequence, payment_expired, duplicate_payment and delivered_amount_mismatch.

Everything is checked against Accepted, which must be the server's requirement; RequirePayment puts it there.

Each settled hash is recorded in an ISettledPaymentStore, and a blob already recorded is refused as duplicate_payment: resubmitting a validated blob makes the node report the original tesSUCCESS, which would otherwise unlock the resource again. The store must be shared by every instance that settles for the same merchant; see ISettledPaymentStore.

A settlement whose outcome the client could not tell - the submit request lost on a reconnect, a lookup that failed while waiting - is waited for once more before it is refused, since the payer's funds may already have moved. If it still cannot be told, the response is settlement_unknown and carries the transaction hash, so the payment can be reconciled rather than lost.

Constructors

| Edit this page View Source

LedgerSettlingFacilitator(IXrplClient)

Initializes a new instance of LedgerSettlingFacilitator with its own InMemorySettledPaymentStore.

Declaration
public LedgerSettlingFacilitator(IXrplClient client)
Parameters
Type Name Description
IXrplClient client

Connected XRPL client used to submit transactions.

Remarks

Replays are caught only by the same instance: keep one facilitator for the application, and use the overload taking an ISettledPaymentStore when several processes settle.

Exceptions
Type Condition
ArgumentNullException

Thrown when client is null.

| Edit this page View Source

LedgerSettlingFacilitator(IXrplClient, ISettledPaymentStore)

Initializes a new instance of LedgerSettlingFacilitator that records settled payments in settledPayments.

Declaration
public LedgerSettlingFacilitator(IXrplClient client, ISettledPaymentStore settledPayments)
Parameters
Type Name Description
IXrplClient client

Connected XRPL client used to submit transactions.

ISettledPaymentStore settledPayments

Store of settled transaction hashes, shared by every instance that settles.

Exceptions
Type Condition
ArgumentNullException

Thrown when an argument is null.

Methods

| Edit this page View Source

VerifyAndSettleAsync(PaymentSignatureEnvelope, CancellationToken)

Verify the signed payment matches the accepted requirement and settle it on-ledger.

Declaration
public Task<PaymentResponseEnvelope> VerifyAndSettleAsync(PaymentSignatureEnvelope envelope, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PaymentSignatureEnvelope envelope
CancellationToken cancellationToken
Returns
Type Description
Task<PaymentResponseEnvelope>
Remarks

Accepted is what the payment is checked against, so it must be the server's own requirement, not the copy the client sent. RequirePayment replaces it before calling; a caller that invokes a facilitator directly must do the same.

Implements

IX402Facilitator
  • Edit this page
  • View Source
In this article
Back to top Generated by DocFX