Rails

A rail is where the payment settles: an EVM chain, Solana, the XRP Ledger, a Lightning node. x402 and MPP each define how a payment is authorized on a rail, and each rail offers different fields a payment can carry: a nonce, a memo, a note, a salt, an invoice field. This page gives, for every rail this package supports, the field H rides in, the pairings that use it, and how the settlement is read.

Each rail's pieces are in their own entry point, such as @integraledger/lcp/evm or @integraledger/lcp/sui: the signed form the payer produces, where H sits in it, and the settlement read. The pairings that use a rail are exported from the protocol's entry point or the rail's own, as the pairings reference lists.

The forms H takes on a railCopy Anchor Link

A rail field holds H in one of these forms:

A field that holds only part of H, or a value derived from it, lets anyone holding the ATR confirm H, but does not let anyone recover H from the chain alone. Each pairing's pattern says which it is: zeroPartyRecoverable is true only where the chain keeps H itself.

This example prints the forms for one H, using each rail's own helper:

import { hash, toLcpString } from "@integraledger/lcp";
import { challengeId } from "@integraledger/lcp/mpp";
import { snNonce } from "@integraledger/lcp/starknet";
import { muxedId } from "@integraledger/lcp/stellar";
import { mppInvoiceId, x402InvoiceId } from "@integraledger/lcp/xrpl";

const h = await hash(new TextEncoder().encode("abc"));

console.log("H:                     ", h);
console.log("LCP string (memos):    ", toLcpString(h));
console.log("Stellar muxed id:      ", muxedId(h));
console.log("Starknet nonce:        ", snNonce(h));
console.log("x402 XRPL InvoiceID:   ", await x402InvoiceId(h));
console.log("MPP XRPL InvoiceID:    ", mppInvoiceId(h));
console.log("MPP challenge id:      ", challengeId(h, 0));

H:                      0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
LCP string (memos):     lcp:sha256:0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Stellar muxed id:       13436514500253700074n
Starknet nonce:         0x27816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
x402 XRPL InvoiceID:    FD9AF578DE2AF5DFC44BE5821EEF4EFE048BB2268AC8F59D58162E8310A3AB73
MPP XRPL InvoiceID:     BA7816BF8F01CFEA414140DE5DAE2223B00361A396177A9CB410FF61F20015AD
MPP challenge id:       ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0.0

Rail by railCopy Anchor Link

Where a profile defines the binding, the pairings reference links it, and the profile states the rail's rules clause by clause.

Peer dependenciesCopy Anchor Link

Some rails parse their wire formats with the rail's own library, which the package declares as an optional peer dependency. Install the one for each rail you use:

Without its peer, a rail's functions refuse with <rail>/peer-missing, or the pairing serves no option. Every other rail needs nothing more than the package.

Reading settlementCopy Anchor Link

status(ref, reader) reads a payment's settlement through a reader you supply: an object with a few read-only calls against one network's endpoint. The package makes those calls and nothing else, so the endpoint, the credentials, the timeouts and the retries are yours. Each status makes a bounded number of calls.

A reader that throws, times out, or answers for another network never makes a payment failed: status answers pending, with the reason unreadable, and a later read can settle it. Failed means the rail itself says so: a reverted, aborted or expired transaction, or one that does not carry this payment.

On EVM chains, a reader rejects with ReaderError and one of the kinds timeout, too-large, transport or malformed. The seller guide builds an EvmReader from one receipt and reads a settlement through it.

Lightning has no settlement read: the invoice and its preimage, which the parties hold, are the proof of payment, and no public ledger shows it. Its pairings give reference and no status.

Recovering H from the chain aloneCopy Anchor Link

On some rails the settled transaction keeps H itself, so anyone can read it back without either party. Those pairings have recover(tx, reader) and pattern.zeroPartyRecoverable set. This example lists them from the registry:

import { BINDINGS } from "@integraledger/lcp";

const recoverable = BINDINGS.filter((b) => b.pattern.zeroPartyRecoverable).map((b) => b.id);
console.log(recoverable.length);
console.log(recoverable.sort().join("\n"));

23
mpp/charge/solana
mpp/charge/usdc/solana
mpp/charge/usdc/stacks
mpp/charge/xrpl
mpp/session/hedera
mpp/session/xrpl
mpp/subscription/tempo
x402/batch-settlement/eip155
x402/batch-settlement/solana
x402/exact/algorand
x402/exact/cardano
x402/exact/casper
x402/exact/ccd
x402/exact/eip155/eip3009
x402/exact/eip155/erc7710-salt
x402/exact/hedera
x402/exact/near
x402/exact/polkadot/lcp-assets-remark
x402/exact/solana
x402/exact/sui
x402/exact/tron/lcp-trc20-memo
x402/exact/tvm
x402/upto/solana

Where the payment is not a public proofCopy Anchor Link

On some pairings the settlement leaves no public record that commits to H: pattern.publicProof is false. H still rides in the challenge, and each pairing's record says what its payment shows. On most of them nothing the buyer signs carries H either. On Lightning the invoice carries H, but the invoice and its preimage are held by the parties, and no public ledger shows them.

For these pairings the seller can advertise an agreement URL: the buyer first pays that URL, whose payment is a public proof of H, and then the full payment. This example lists the x402 and MPP pairings it applies to:

import { BINDINGS } from "@integraledger/lcp";

const rails = BINDINGS.filter((b) => /^(x402|mpp)\//.test(b.id) && !b.pattern.publicProof).map((b) => b.id);
console.log(rails.sort().join("\n"));

mpp/charge/card
mpp/charge/evm/hash
mpp/charge/evm/transaction
mpp/charge/lightning
mpp/charge/nearintents
mpp/charge/stripe
mpp/session/lightning
mpp/subscription/stripe
x402/batch-settlement/cloudflare
x402/exact/aptos
x402/exact/eip155/erc7710
x402/exact/hedera/transfer-executor
x402/exact/lnbtc
x402/exact/lnbtc/invoice-named

The checkout pairings are the same where the buyer's approval does not sign H; see Agentic checkouts.

NextCopy Anchor Link

• Binding: the binding patterns and the pattern record.
• x402 and MPP: the protocols these rails settle under.