@integraledger/lcp-binding-core

The carrier codec, and the WeldAdapter port the EVM rail bindings implement.

Two things live here, and nothing chain-specific does. The carrier codec encodes and decodes an LCP reference across the three shapes the specification defines. The WeldAdapter port is the interface the three EVM rail bindings satisfy, so a caller can weld a record to an EVM settlement without knowing which of them it is on.

npm install @integraledger/lcp-binding-core

Depends only on @integraledger/lcp-kernel — no chain SDK, and depcruise holds it that way.

The three carrier shapes

import {
  encodeLegalContextString, decodeLegalContextString,
  encodeLegalContextJson, encodeLegalContextBytes,
  type LegalContextRef,
} from "@integraledger/lcp-binding-core";

// Annotated, not inferred: a bare literal widens `type` to `string`, which is not a `CarrierType`.
const ref: LegalContextRef = { type: "sha256", value: "0x7f7f…" };

encodeLegalContextString(ref);  // "lcp:sha256:0x7f7f…"   — a string field
encodeLegalContextJson(ref);    // { legalContext: { type, value } } — a JSON field
encodeLegalContextBytes(ref);   // Uint8Array(32)        — a raw-bytes field

decodeLegalContextString("lcp:sha256:0x7f7f…"); // → { type, value }

Only sha256 has a fixed-width byte form; asking for the byte carrier with any other type is a typed refusal (carrier/no-byte-form) rather than a truncation.

Unknown types are ignored; corrupt ones are not

import { decodeLegalContextString } from "@integraledger/lcp-binding-core";

decodeLegalContextString("lcp:unknown-type:whatever"); // undefined — ignored
decodeLegalContextString("lcp:sha256:");               // throws carrier/malformed

The type registry is open: an unrecognized type decodes to undefined and is skipped, so a rail carrying a carrier type this version has never heard of does not break a verifier built against this version. That is forward-compatibility, and it is deliberate.

A recognized type with a malformed or empty value is the opposite case — that is a corrupt carrier, and it fails loudly. The distinction matters: silently ignoring a corrupt sha256 carrier would report "no legal context here" about a record that plainly has one.

Structure parsing and registry narrowing are separate functions, because they answer different questions. parseLcpString splits the shape without consulting the registry; decodeLegalContextString then narrows to known types.

The WeldAdapter port

The three EVM rail bindings implement this interface — bind an ATR hash into a pre-settlement artifact, recover it from a settled one, observe lifecycle transitions. Consumers depend on the port, not on any chain SDK.

It is not a universal port, and the ten non-EVM rails deliberately do not implement it. Its shape is EVM's: SettlementRef.txHash is a 0x-hex value and ChainReader speaks eth_getLogs. A Sui transaction digest, a Daml contractId or an XRPL memo cannot pass through that without lying about the rail, so each of those bindings exposes a rail-native surface and says so in its first docblock. Unifying the port across EVM and non-EVM is future work; pretending it is already unified would cost a consumer more than it saves.

The dependency rule is enforced structurally rather than by convention: dependency-cruiser fails the build if a chain SDK reaches outside its own binding package, so viem cannot leak into a Solana caller's graph, and nothing in this package imports a chain library at all.

Requirement ids

This package's source and its messages cite short ids — ATA-3, RCS-5, CMP-6 and their kin. They are not LCP clause numbers. LCP is cited by section (§8.3.1, §C.2); anything shaped XXX-n comes from Integra's functional specification of what a complete agent transaction requires, the fourteen families below. Nothing in this package's behaviour depends on them, and where an id and an LCP section disagree the section governs.

| | | | | |---|---|---|---| | IDN identity | ASP authority to spend | ATA authority to accept terms | TRM the terms record | | RCS recourse | PAY payment and settlement | WLD the transactional weld | OFR offer integrity | | FRC fraud, risk, and compliance | OPS commercial operations | DSC discovery and reputation | ORC orchestration | | CMP composition | PRS persistence and verification infrastructure | | |

Requires Node >= 24. Part of the Legal Context Protocol open layer — see the documentation and the package index. Apache-2.0.