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
Implements
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 SourceLedgerSettlingFacilitator(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 |
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 SourceVerifyAndSettleAsync(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.