Skip to content
Integra Protocol
API

@integraledger/lcp

The exports of @integraledger/lcp.

Interfaces

CarrierAfterH

The optional member of a pairing whose carrier the seller writes after H: advertise's checks and placement, without the checks on that carrier.

Methods

advertiseBeforeCarrier()?

optional advertiseBeforeCarrier(doc, h, link, offer, agreementUrl?): unknown

Parameters
ParameterType
docnever
h`0x${string}`
linkstring
offernever
agreementUrl?string
Returns

unknown

PresentedOn

What the buyer presents as payment, per surface: the union of the payment types of every pairing on it. Every pairing's bound and reference take unknown and check what they are given.

Properties

PropertyTypeDescription
ackJsonACK defines no payer signature; its bound refuses whatever is presented.
acpPresented-
ap2Presented-
cardTapPresented | ViImmediate | ViAutonomous-
mppMppCredential-
ucpPresented-
x402PaymentPayload | HederaPaymentPayload | ExecutorPaymentPayload | LnPaymentPayload | AptosPaymentPayload | AvmPaymentPayload | CardanoPaymentPayload | CasperPaymentPayload | CcdPaymentPayload | NearPayment | PolkadotPaymentPayload | StarknetPayment | SuiPaymentPayload | TronPayment | TvmPayment | BatchPaymentPayload | CloudflarePaymentPayload | SvmPaymentPayload | StellarPaymentPayload | XrplPaymentPayload | UptoSvmPaymentPayload-

PushMode

The optional member of a push-mode pairing: the transaction its credential names, or undefined.

Methods

landedTx()?

optional landedTx(presented): string | undefined

Parameters
ParameterType
presentedunknown
Returns

string | undefined

TieRequestOn

The request a surface's tie takes with its options: x402's request commitment; the others' tie takes none.

Properties

PropertyType
acknever
acpnever
ap2never
cardnever
mppnever
ucpnever
x402RequestCommitment

TxSpelling

The optional member of a pairing whose rail spells one transaction id more than one way: the id in the one spelling a record keeps.

Methods

txId()?

optional txId(tx): string

Parameters
ParameterType
txstring
Returns

string

Type Aliases

AtrHash

AtrHash = `0x${string}`

0x followed by 64 hex digits. Every hash this module emits is lowercase.

Binding

Binding = X402Binding | MppBinding | typeof paymentRequest | typeof delegated | typeof undelegated | typeof checkoutMandate | typeof viAutonomous | typeof viImmediate | typeof sellerReference | typeof visaTap | typeof bookingAp2Mandate | typeof bookingUnsigned | typeof ap2Mandate | typeof unsigned & PushMode & CarrierAfterH & TxSpelling

A pairing of protocol, scheme and rail.

CoreRefusal

CoreRefusal = object

Properties

PropertyType
code"core/slot-name" | "core/slot-reserved" | "core/slot-duplicate" | "core/content-not-json" | "core/binding-not-json" | "core/too-large"
refusedtrue

Json

Json = string | number | boolean | null | readonly Json[] | {[k: string]: Json; }

A JSON value. Numbers in a binding value must be safe integers.

MppBinding

MppBinding = typeof MPP_BINDINGS[number]

An MPP pairing of intent and method.

PairingId

PairingId = Binding["id"]

PairingOn

PairingOn<S> = Extract<PairingId, `${S}/${string}`>

The pairing ids of one surface.

Type Parameters

Type Parameter
S extends Surface

Presented

Presented = PresentedOn[Surface]

What the buyer presents as payment.

Refusal

Refusal = object

A refusal returned as a value. code is <entry point>/<reason>.

Properties

PropertyType
codestring
refusedtrue

Surface

Surface = keyof PresentedOn

The surfaces: a pairing id's first "/" segment.

X402Binding

X402Binding = typeof exactEip3009 | typeof authCaptureEip3009 | typeof authCapturePermit2 | typeof batchCloudflare | typeof batchEvm | typeof batchSvm | typeof exactAvm | typeof exactAptos | typeof exactCardano | typeof exactCasper | typeof exactCcd | typeof exactErc7710 | typeof exactErc7710Salt | typeof exactPermit2 | typeof exactHedera | typeof exactHederaExecutor | typeof exactLnbtc | typeof exactLnbtcNamed | typeof exactNear | typeof exactPolkadotRemark | typeof exactSvm | typeof exactStarknet | typeof exactStellar | typeof exactSui | typeof exactTronMemo | typeof exactTvm | typeof exactXrpl | typeof uptoPermit2 | typeof uptoSvm

An x402 pairing of scheme and rail.

Variables

BINDINGS

const BINDINGS: readonly Binding[]

Every pairing this package implements.

MAX_JSON_DEPTH

const MAX_JSON_DEPTH: 64 = 64

The deepest nesting of arrays and objects in any JSON this package writes or reads.

Functions

assemble()

assemble(id, binding, content, limits?): Promise<CoreRefusal | { atrHash: `0x${string}`; bytes: Uint8Array; }>

Writes the ATR's bytes and hashes them. The same inputs always give the same bytes. Every problem with the inputs is returned as a refusal.

Parameters

ParameterType
idstring
bindingreadonly [string, Json]
contentreadonly readonly [string, Uint8Array<ArrayBufferLike>][]
limits?{ maxBytes?: number; }
limits.maxBytes?number

Returns

Promise<CoreRefusal | { atrHash: `0x${string}`; bytes: Uint8Array; }>

canonicalJson()

canonicalJson(v): string | CoreRefusal

The RFC 8785 form of v: object members sorted by the UTF-16 code units of their names, recursively, and every primitive written as JSON.stringify writes it. Refuses what digestJson refuses.

Parameters

ParameterType
vJson

Returns

string | CoreRefusal

canonicalTx()

canonicalTx(binding, tx): string

A transaction id as a record keeps it: the pairing's txId, where it has one, else the id unchanged.

Parameters

ParameterType
bindingBinding | undefined
txstring

Returns

string

digestJson()

digestJson(v): Promise<`0x${string}` | CoreRefusal>

SHA-256 over the RFC 8785 form of v. Refuses a value deeper than 64 levels, a non-finite number, a string with an unpaired surrogate, or anything that is not a JSON value.

Parameters

ParameterType
vJson

Returns

Promise<`0x${string}` | CoreRefusal>

fromLcpString()

fromLcpString(s): `0x${string}` | null

Decodes lcp:sha256:0x…, returning the lowercase hash, or null for anything else.

Parameters

ParameterType
sstring

Returns

`0x${string}` | null

fromLegalContext()

fromLegalContext(o): { h: `0x${string}`; url: string; } | null

Decodes the structured form: type "sha256", a 32-byte hash, and an https:// link in either spelling. Returns the lowercase hash and the link, or null for anything else, including two spellings that disagree. Other members are ignored.

Parameters

ParameterType
ounknown

Returns

{ h: `0x${string}`; url: string; } | null

fromRawBytes()

fromRawBytes(b): `0x${string}` | null

The lowercase hash of exactly 32 raw bytes, or null.

Parameters

ParameterType
bUint8Array

Returns

`0x${string}` | null

hash()

hash(bytes): Promise<`0x${string}`>

SHA-256 over the bytes as given, as 0x and lowercase hex.

Parameters

ParameterType
bytesUint8Array

Returns

Promise<`0x${string}`>

hashEquals()

hashEquals(a, b): boolean

True when a and b are each 0x and 64 hex digits, in either case, and decode to the same 32 bytes (LCP §2.5). Anything else is false.

Parameters

ParameterType
astring
bstring

Returns

boolean

isHashWithNonHttpsLink(info): boolean

True for a structured form's inner object that fromLegalContext would decode except that its one link, in either spelling, is a link of another scheme (isOtherSchemeLink).

Parameters

ParameterType
infounknown

Returns

boolean

isHttpsLink(s): s is string

The one https-link rule. The raw string holds no whitespace, control character or backslash; it parses as an absolute URL; its scheme is https, compared case-insensitively (RFC 3986 §3.1); its authority has a host, a DNS name or an IP literal, and no userinfo.

Parameters

ParameterType
sunknown

Returns

s is string

isOtherSchemeLink(s): s is string

True for a string of at most 2048 characters that parses as an absolute URL whose scheme is not https: the one failing link refused as link-not-https. Every other failing link is legal-context-malformed.

Parameters

ParameterType
sunknown

Returns

s is string

jsonWithinDepth()

jsonWithinDepth(text): boolean

True when no array or object in JSON text is nested more than MAX_JSON_DEPTH deep. Brackets inside strings are skipped; nothing else about the text is checked.

Parameters

ParameterType
textstring

Returns

boolean

newAtrId()

newAtrId(): string

A random RFC 9562 version 4 UUID, lowercase.

Returns

string

pairingOf()

pairingOf(option): PairingOn<"x402"> | undefined

The x402 pairing that serves an option: a Lightning option's by lnbtcPairingOf, which names x402/exact/lnbtc for an option whose invoice is not yet written; else the first x402 pairing in BINDINGS whose read offers it, on a document holding that option alone. Undefined when none does.

Parameters

ParameterType
optionPaymentRequirements

Returns

PairingOn<"x402"> | undefined

pairingsOfPlaced()

pairingsOfPlaced(c): readonly MppPairing[]

The pairings a placed challenge offers: pairingsOf over the challenge with its opaque removed, so the LCP members place wrote are not read as an occupied carrier. None when the challenge does not read.

Parameters

ParameterType
cMppChallenge

Returns

readonly MppPairing[]

parseJson()

parseJson(text): unknown

The value of JSON text nested at most MAX_JSON_DEPTH deep; undefined for text that is deeper or is not JSON.

Parameters

ParameterType
textstring

Returns

unknown

toLcpString()

toLcpString(h): string

LCP §8.1 string form: lcp:sha256:0x…. Throws TypeError when h is not a 32-byte hash.

Parameters

ParameterType
h`0x${string}`

Returns

string

toLegalContext()

toLegalContext(h, url, spelling?): object

LCP §8.1 structured form, with the link beside the digest. spelling "snake" writes legal_context_url. Throws TypeError when h is not a 32-byte hash or url is not an https:// URL.

Parameters

ParameterTypeDefault value
h`0x${string}`undefined
urlstringundefined
spelling"camel" | "snake""camel"

Returns

object

NameType
legalContextobject
legalContext.legal_context_url?string
legalContext.legalContextUrl?string
legalContext.type"sha256"
legalContext.value`0x${string}`

toRawBytes()

toRawBytes(h): Uint8Array

The raw 32 bytes of a hash. Throws TypeError when h is not a 32-byte hash.

Parameters

ParameterType
h`0x${string}`

Returns

Uint8Array

References

LcpPattern

Re-exports LcpPattern

Last updated on

Vector files

Every vector file @integraledger/lcp ships, and what it fixes.

@integraledger/lcp/a2a

The exports of @integraledger/lcp/a2a.

On this page

InterfacesCarrierAfterHMethodsadvertiseBeforeCarrier()?ParametersReturnsPresentedOnPropertiesPushModeMethodslandedTx()?ParametersReturnsTieRequestOnPropertiesTxSpellingMethodstxId()?ParametersReturnsType AliasesAtrHashBindingCoreRefusalPropertiesJsonMppBindingPairingIdPairingOnType ParametersPresentedRefusalPropertiesSurfaceX402BindingVariablesBINDINGSMAX_JSON_DEPTHFunctionsassemble()ParametersReturnscanonicalJson()ParametersReturnscanonicalTx()ParametersReturnsdigestJson()ParametersReturnsfromLcpString()ParametersReturnsfromLegalContext()ParametersReturnsfromRawBytes()ParametersReturnshash()ParametersReturnshashEquals()ParametersReturnsisHashWithNonHttpsLink()ParametersReturnsisHttpsLink()ParametersReturnsisOtherSchemeLink()ParametersReturnsjsonWithinDepth()ParametersReturnsnewAtrId()ReturnspairingOf()ParametersReturnspairingsOfPlaced()ParametersReturnsparseJson()ParametersReturnstoLcpString()ParametersReturnstoLegalContext()ParametersReturnstoRawBytes()ParametersReturnsReferencesLcpPattern