@integraledger/lcp-binding-stellar 0.9.0

package/src/adapter.ts

@@ -0,0 +1,316 @@
+/**
+ * The Stellar CAP-67 muxed-address adapter — thin I/O with @stellar/stellar-sdk isolated here. Like
+ * binding-solana it intentionally does NOT implement binding-core's `WeldAdapter`: that port is EVM-shaped
+ * (`SettlementRef.txHash` is a `0x`-hex value, `ChainReader` speaks `eth_getLogs`), and Stellar speaks
+ * hex tx hashes over Horizon + CAP-67 M-address destinations. Rather than lie through those types, this
+ * exposes a Stellar-native surface (a tx-hash ref, a `StellarReader` port) alongside the shared,
+ * chain-agnostic `BindingManifest`. Unifying the port shape across EVM and non-EVM rails is future work;
+ * forcing it here would misrepresent the rail.
+ *
+ * ★ THE SURFACE IS CONFIRM-NOT-RECOVER, BY THE RAIL'S NATURE. Only `atrHash[:8]` rides in the CAP-67 mux
+ * id (8 bytes); the full 32-byte atrHash never touches the chain. So:
+ *   - `propose(atrHash, basePubkey)` builds the muxed M-address destination the buyer transfers to.
+ *   - `verify(atrHash, ref)` is the PRIMARY honest surface: it confirms the known atrHash's prefix-8 equals
+ *     the settlement's on-chain mux id → `Outcome<{ confirmed: true; muxIdPrefix8Hex }>` or a
+ *     `verification-failure` Refusal. (You bring the atrHash — from `extensions.legalContext.info` — the chain
+ *     confirms the match.)
+ *   - `recover(ref)` does NOT return a full atrHash (it cannot — the chain holds 8 bytes). It returns an
+ *     explicitly-PARTIAL `{ muxIdPrefix8Hex }` documenting that only the prefix is on-chain, so a caller
+ *     cannot mistake it for a recovered hash. If you want the atrHash, use `verify` with the off-chain hash.
+ *   - `observe` reports the settled transition alongside the on-chain mux prefix.
+ *   - `enumerate` is the best-effort account scan the manifest declares (`forwardIndexable: false`).
+ *
+ * ★ EVERY SURFACE GATES ON TRANSACTION SUCCESS FIRST (`StellarSettlementView.successful`). A failed
+ * Stellar transaction is still recorded in the ledger with its fee charged, and the operation's `to`
+ * destination lives in the transaction ENVELOPE — so the M-address stays readable on a `txFAILED` result.
+ * The confirm-not-recover posture does NOT mitigate that: it changes WHAT is proven (a prefix match rather
+ * than a recovered hash), never WHETHER settlement occurred. Without the gate, `verify` returns
+ * `confirmed: true` and `observe` returns `state: "settled"` for a transaction that moved nothing.
+ */
+import type {
+  BindingManifest,
+  Outcome,
+  Refusal,
+} from "@integraledger/lcp-binding-core";
+import {
+  deriveMuxId,
+  encodeMuxedAddress,
+  recoverMuxIdPrefix8,
+  verifyMuxedBinding,
+} from "./mux.js";
+
+/** A Stellar settlement reference — a transaction hash (64-hex, as Horizon reports it). */
+export interface StellarSettlementRef {
+  txHash: string;
+}
+
+/** The minimal on-chain view of a settlement this binding cares about: the CAP-67 M-address the SAC
+ *  `transfer` paid to, plus whether the transaction actually succeeded. A reader implementation decodes the
+ *  destination from the tx's single `transfer(from, to, amount)` op. `null` when the tx has no muxed
+ *  destination. */
+export interface StellarSettlementView {
+  /** The `to` destination of the SAC transfer, a CAP-67 M-address (starts with `M`), or null if none. */
+  muxedDestination: string | null;
+  /**
+   * Horizon's `successful` field for the transaction. ONLY `true` is a settlement: a Stellar transaction
+   * that fails is still recorded in the ledger with its fee charged, and the operation's `to` destination
+   * lives in the transaction ENVELOPE — so the M-address stays readable on a `txFAILED` result. Confirming
+   * it would mint a settlement record out of a failure. Fail-closed: `false` AND absent are both refused,
+   * because a reader that supplied no outcome gave no evidence of success (mirrors binding-solana's
+   * `err === null` gate and binding-xrpl's validated/tesSUCCESS gate). A faithful Horizon reader always
+   * supplies this field; note `/accounts/{id}/transactions` omits failed transactions unless
+   * `include_failed=true`, while `/transactions/{hash}` returns them either way.
+   */
+  successful?: boolean;
+}
+
+/**
+ * Did this transaction actually settle? Pure, fail-closed — only an explicit `true` counts. Every surface
+ * in this binding (`verify`, `recover`, `observe`, `enumerate`) gates on this before honouring a mux id:
+ * the confirm-not-recover posture changes WHAT is proven (a prefix match rather than a recovered hash),
+ * never WHETHER settlement occurred.
+ */
+export function isSettledSuccessfully(view: StellarSettlementView): boolean {
+  return view.successful === true;
+}
+
+/** Reads confirmed Stellar transactions — an injected port over Horizon / the SDK. */
+export interface StellarReader {
+  settlementView(txHash: string): Promise<StellarSettlementView>;
+  /** Tx hashes touching an account's payment history (best-effort scan input for `enumerate`). */
+  transactionsFor(account: string, limit?: number): Promise<string[]>;
+}
+
+/** Build the CAP-67 muxed M-address destination carrying `atrHash[:8]` for a seller base G-pubkey. This is
+ *  the `payTo` the buyer's SAC transfer targets; the buyer's signature over that transfer welds the mux id
+ *  (signature-grade). Throws on a malformed atrHash / base pubkey (fail-fast). */
+export function buildMuxedDestination(
+  atrHash: string,
+  baseGPubkey: string,
+): string {
+  return encodeMuxedAddress(baseGPubkey, deriveMuxId(atrHash));
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = "0x";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+/** The result of `recover`: explicitly PARTIAL. `muxIdPrefix8Hex` is `0x` + 16 hex chars = `atrHash[:8]`,
+ *  NOT a full atrHash. `note` states the truncation so no caller mistakes it for a recovered hash. */
+export interface StellarMuxPrefixRecovery {
+  /** `0x`-prefixed hex of the 8 on-chain mux bytes (`atrHash[:8]`). NOT the full 32-byte atrHash. */
+  muxIdPrefix8Hex: string;
+  partial: true;
+  note: string;
+}
+
+/** The result of `verify`: a confirmed prefix-8 match against a KNOWN atrHash. */
+export interface StellarMuxConfirmation {
+  confirmed: true;
+  /** `0x`-prefixed hex of the on-chain mux id that matched `atrHash[:8]`. */
+  muxIdPrefix8Hex: string;
+}
+
+/** The Stellar rail's surface, and the one whose shape differs most from the others — because only 8 bytes
+ *  ride on-chain. A CAP-67 mux id is 8 bytes, so the full atrHash does not fit, and `recover` therefore
+ *  answers a PREFIX, never a hash. {@link StellarAdapter.verify} is the primary method here: you bring the
+ *  atrHash from off-chain and the chain confirms its first 8 bytes match. A caller reaching for `recover`
+ *  expecting the other rails' behaviour is the mistake this rail is shaped to make impossible. */
+export interface StellarAdapter {
+  manifest: BindingManifest;
+  /** Build the muxed M-address destination the buyer transfers to (welds `atrHash[:8]`). */
+  propose(atrHash: string, baseGPubkey: string): string;
+  /**
+   * CONFIRM (primary): does the settlement's on-chain mux id equal the KNOWN atrHash's prefix-8? Returns a
+   * confirmation with the matched prefix, or a `verification-failure` Refusal on mismatch / no muxed
+   * destination. You supply the atrHash (from off-chain `extensions.legalContext.info`); the chain confirms it.
+   */
+  verify(
+    atrHash: string,
+    ref: StellarSettlementRef,
+    reader: StellarReader,
+  ): Promise<Outcome<StellarMuxConfirmation>>;
+  /**
+   * RECOVER — explicitly PARTIAL. Returns only the 8-byte on-chain mux prefix (`atrHash[:8]`), never a full
+   * atrHash (the chain does not carry one). A `verification-failure` Refusal when the tx has no muxed
+   * destination. To obtain the atrHash, use `verify` with the off-chain hash.
+   */
+  recover(
+    ref: StellarSettlementRef,
+    reader: StellarReader,
+  ): Promise<Outcome<StellarMuxPrefixRecovery>>;
+  /** Report the settled transition (the tx is confirmed and its destination is a CAP-67 muxed M-address). */
+  observe(
+    ref: StellarSettlementRef,
+    reader: StellarReader,
+  ): Promise<Outcome<{ state: "settled"; muxIdPrefix8Hex: string }>>;
+  /**
+   * Best-effort account scan for settlements whose mux id matches `atrHash[:8]` (NOT a native index — see
+   * the manifest's `forwardIndexable: false`). Confirms, per tx, against the known atrHash.
+   */
+  enumerate(
+    atrHash: string,
+    account: string,
+    reader: StellarReader,
+    limit?: number,
+  ): Promise<StellarSettlementRef[]>;
+}
+
+/**
+ * The `note` every partial recovery carries, exported because callers receive it and matching on a string
+ * they cannot import is guesswork. It names the off-chain slot the x402 placement actually writes —
+ * `extensions.legalContext.info` — and `rail-invariants` asserts that against the placement's own manifest,
+ * because a reader who follows this instruction to a slot nothing writes concludes the reference is absent.
+ */
+export const STELLAR_PREFIX_NOTE =
+  "PARTIAL: only atrHash[:8] rides in the CAP-67 mux id — this is the 8-byte on-chain prefix, NOT the full atrHash; obtain the full hash off-chain (extensions.legalContext.info) and use verify() to confirm the match";
+
+/** Construct the Stellar adapter. **The manifest is injected, not baked in** — pass this package's own
+ *  `STELLAR_MANIFEST`; a manifest whose `rail` is not `"stellar"` throws, because an adapter over another
+ *  rail's manifest would publish that rail's claims as its own. This is the package's entry point. */
+export function createStellarAdapter(
+  manifest: BindingManifest,
+): StellarAdapter {
+  // Fail-fast: an adapter constructed over another rail's manifest would report that rail's claims as
+  // this one's. The EVM adapters bake their module const in; the injectable factories refuse instead.
+  // Stryker disable next-line all: the guard runs during test-module load (the repository's
+  // test suite constructs the adapter at describe scope), so its mutants are 'static' — outside the vitest
+  // runner's per-test attribution and unkillable by any test that in fact kills them behaviorally
+  // (each rail pins both arms: valid manifest constructs, wrong rail throws by message).
+  if (manifest.rail !== "stellar")
+    throw new Error(
+      `createStellarAdapter: manifest.rail "${manifest.rail}" is not "stellar"`,
+    );
+  // Closure helpers (not `this`) so the returned methods stay destructure-safe.
+  /** Every refusal on this rail is a verification failure, namespaced `stellar/…` (mirrors placement.ts). */
+  const refuse = (code: string, detail: string): Refusal => ({
+    refused: true,
+    haltClass: "verification-failure",
+    code: `stellar/${code}`,
+    detail,
+  });
+
+  /** The refusal a transaction that did not succeed earns — never a mismatch, never a missing destination. */
+  const unsuccessful = (txHash: string): Refusal =>
+    refuse(
+      "unsuccessful-transaction",
+      `transaction ${txHash} did not succeed (Horizon successful !== true) — its CAP-67 destination is not a settlement`,
+    );
+
+  const noMuxedDestination = (txHash: string): Refusal =>
+    refuse("no-muxed-destination", `no CAP-67 muxed destination in ${txHash}`);
+
+  /**
+   * The on-chain mux prefix of a SUCCESSFUL settlement. Returns the refusal reason as a discriminated
+   * value so `recover` and `observe` report WHY: a failed transaction is not "no destination".
+   */
+  async function onChainPrefix(
+    ref: StellarSettlementRef,
+    reader: StellarReader,
+  ): Promise<
+    | { prefix: Uint8Array; muxedDestination: string }
+    | { reason: "no-muxed-destination" }
+    | { reason: "unsuccessful" }
+  > {
+    const view = await reader.settlementView(ref.txHash);
+    if (view.muxedDestination === null)
+      return { reason: "no-muxed-destination" };
+    if (!isSettledSuccessfully(view)) return { reason: "unsuccessful" };
+    // DECODE BEFORE COMPARING. A destination that is not a valid M-address (a plain G-address, a truncated
+    // StrKey) carries no mux id at all — that is "no muxed destination", never "the wrong atrHash". Every
+    // surface routes through here so the four of them cannot disagree about what a given view means.
+    const prefix = recoverMuxIdPrefix8(view.muxedDestination);
+    if (prefix === null) return { reason: "no-muxed-destination" };
+    return { prefix, muxedDestination: view.muxedDestination };
+  }
+
+  /** The refusal for whichever reason `onChainPrefix` gave — shared by all four surfaces. */
+  const refusalFor = (
+    reason: "no-muxed-destination" | "unsuccessful",
+    txHash: string,
+  ): Refusal =>
+    reason === "unsuccessful"
+      ? unsuccessful(txHash)
+      : noMuxedDestination(txHash);
+
+  return {
+    manifest,
+
+    propose(atrHash: string, baseGPubkey: string): string {
+      return buildMuxedDestination(atrHash, baseGPubkey);
+    },
+
+    async verify(
+      atrHash: string,
+      ref: StellarSettlementRef,
+      reader: StellarReader,
+    ): Promise<Outcome<StellarMuxConfirmation>> {
+      // ★ The success gate and the decode both run BEFORE the prefix match: a failed transaction is not
+      // "the wrong ATR" (its envelope still carries the M-address), and an undecodable destination is not
+      // one either. `mux-prefix-mismatch` therefore means strictly: there WAS a mux id, and it was wrong.
+      const found = await onChainPrefix(ref, reader);
+      if ("reason" in found) return refusalFor(found.reason, ref.txHash);
+      if (!verifyMuxedBinding({ muxedM: found.muxedDestination, atrHash }))
+        return refuse(
+          "mux-prefix-mismatch",
+          `on-chain mux id != atrHash[:8] for ${ref.txHash}`,
+        );
+      return {
+        ok: true,
+        value: { confirmed: true, muxIdPrefix8Hex: toHex(found.prefix) },
+      };
+    },
+
+    async recover(
+      ref: StellarSettlementRef,
+      reader: StellarReader,
+    ): Promise<Outcome<StellarMuxPrefixRecovery>> {
+      const found = await onChainPrefix(ref, reader);
+      if ("reason" in found) return refusalFor(found.reason, ref.txHash);
+      return {
+        ok: true,
+        value: {
+          muxIdPrefix8Hex: toHex(found.prefix),
+          partial: true,
+          note: STELLAR_PREFIX_NOTE,
+        },
+      };
+    },
+
+    async observe(
+      ref: StellarSettlementRef,
+      reader: StellarReader,
+    ): Promise<Outcome<{ state: "settled"; muxIdPrefix8Hex: string }>> {
+      const found = await onChainPrefix(ref, reader);
+      if ("reason" in found) return refusalFor(found.reason, ref.txHash);
+      return {
+        ok: true,
+        value: { state: "settled", muxIdPrefix8Hex: toHex(found.prefix) },
+      };
+    },
+
+    async enumerate(
+      atrHash: string,
+      account: string,
+      reader: StellarReader,
+      limit?: number,
+    ): Promise<StellarSettlementRef[]> {
+      const hashes = await reader.transactionsFor(account, limit);
+      const out: StellarSettlementRef[] = [];
+      for (const txHash of hashes) {
+        const view = await reader.settlementView(txHash);
+        // A failed transaction's envelope still carries the M-address — the scan must skip it, or a
+        // ledger full of failures enumerates as a ledger full of settlements.
+        if (
+          view.muxedDestination !== null &&
+          isSettledSuccessfully(view) &&
+          verifyMuxedBinding({ muxedM: view.muxedDestination, atrHash })
+        )
+          out.push({ txHash });
+      }
+      return out;
+    },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,74 @@
+/**
+ * Stellar network constants for the LCP CAP-67 muxed-address binding. The binding rides
+ * `mux_id = atrHash[:8]` inside a CAP-67 muxed M-address that the seller advertises as `payTo`; the buyer
+ * signs a Soroban SAC `transfer(from, to, amount)` whose `to` is that M-address, so the buyer's signature
+ * commits the 8-byte prefix atomically with the transfer (canonical LCP §8.3.1 Native Field per the LCP
+ * per-chain binding table — the CAP-67 muxed id, not an overlay contract).
+ *
+ * ★ ONLY 8 bytes ride on-chain. A CAP-67 muxed id is exactly 8 bytes, so the FULL 32-byte atrHash does not
+ * fit — the on-chain artifact confirms `atrHash[:8]`, it does not recover the whole hash (that comes from
+ * off-chain `extensions.legalContext.info`). See `mux.ts` and the manifest for how the surface stays honest.
+ */
+
+/** The single canonical mux-id derivation scheme LCP-on-Stellar commits to: `mux_id = atrHash[:8]`. The
+ *  prefix is deliberately public (project_stellar_mux_prefix8_audit) — any observer holding the atrHash can
+ *  confirm the on-chain mux id matches, which IS the audit-trail property the protocol wants. No HMAC /
+ *  per-seller-key variant is wired (that would trade auditability for unlinkability, which is not wanted). */
+export const MUX_SCHEME = "atrHash-prefix-8" as const;
+
+/** The mux id is the first 8 bytes of the 32-byte atrHash. */
+export const MUX_ID_BYTES = 8;
+
+/** The two networks. Stellar's mainnet is `pubnet`, not `"mainnet"` — the SDK's own name, kept. */
+export type StellarNetwork = "testnet" | "pubnet";
+
+/** Per-network constants. Two endpoints, because the write and the read use different ones: the transfer
+ *  is a Soroban SAC call (`sorobanRpcUrl`, for the caller that builds and submits it) while recovery reads
+ *  the transaction envelope back through Horizon (`horizonUrl`). This package itself performs no HTTP —
+ *  `sorobanRpcUrl` is carried for the caller's benefit and nothing here consumes it. */
+export interface StellarNetworkConfig {
+  network: StellarNetwork;
+  /** Network passphrase used for tx signing / envelope decoding. */
+  networkPassphrase: string;
+  /** Horizon REST base URL. */
+  horizonUrl: string;
+  /** Soroban RPC URL. */
+  sorobanRpcUrl: string;
+  /** Circle-issued USDC Soroban Asset Contract id on this network. */
+  usdcSacContractId: string;
+}
+
+/** Stellar network passphrases (from the SDK's `Networks`; inlined here so constants stays SDK-free). */
+export const TESTNET_PASSPHRASE = "Test SDF Network ; September 2015";
+/** The pubnet passphrase. Note the spacing — ` ; ` with spaces either side is part of the string, and the
+ *  passphrase is hashed into every signature, so a single wrong character produces a transaction that
+ *  verifies against nothing. */
+export const PUBNET_PASSPHRASE =
+  "Public Global Stellar Network ; September 2015";
+
+const TESTNET: StellarNetworkConfig = {
+  network: "testnet",
+  networkPassphrase: TESTNET_PASSPHRASE,
+  horizonUrl: "https://horizon-testnet.stellar.org",
+  sorobanRpcUrl: "https://soroban-testnet.stellar.org",
+  usdcSacContractId: "CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU",
+};
+
+const PUBNET: StellarNetworkConfig = {
+  network: "pubnet",
+  networkPassphrase: PUBNET_PASSPHRASE,
+  horizonUrl: "https://horizon.stellar.org",
+  sorobanRpcUrl: "https://mainnet.sorobanrpc.com",
+  usdcSacContractId: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
+};
+
+/** The constants for one network. Both are usable — the CAP-67 muxed id is a ledger primitive, so nothing
+ *  has to be deployed first. */
+export function getStellarConfig(
+  network: StellarNetwork,
+): StellarNetworkConfig {
+  return network === "testnet" ? TESTNET : PUBNET;
+}
+
+/** USDC on Stellar has 7 decimals — 1 USDC = 10_000_000 base units. */
+export const USDC_DECIMALS = 7;

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  buildMuxedDestination,
+  createStellarAdapter,
+  isSettledSuccessfully,
+  STELLAR_PREFIX_NOTE,
+  type StellarAdapter,
+  type StellarMuxConfirmation,
+  type StellarMuxPrefixRecovery,
+  type StellarReader,
+  type StellarSettlementRef,
+  type StellarSettlementView,
+} from "./adapter.js";
+export {
+  getStellarConfig,
+  MUX_ID_BYTES,
+  MUX_SCHEME,
+  PUBNET_PASSPHRASE,
+  type StellarNetwork,
+  type StellarNetworkConfig,
+  TESTNET_PASSPHRASE,
+  USDC_DECIMALS,
+} from "./constants.js";
+export { STELLAR_MANIFEST } from "./manifest.js";
+export {
+  type DecodedMuxedAddress,
+  decodeMuxedAddress,
+  deriveMuxId,
+  encodeMuxedAddress,
+  recoverMuxIdPrefix8,
+  verifyMuxedBinding,
+} from "./mux.js";

package/src/manifest.ts

@@ -0,0 +1,50 @@
+import type { BindingManifest } from "@integraledger/lcp-binding-core";
+
+/**
+ * The Stellar CAP-67 muxed-address binding manifest.
+ *
+ * **pattern = "native-field"** — the binding rides `mux_id` inside a CAP-67 muxed M-address (an existing
+ * Stellar account primitive), not an overlay contract (canonical LCP §8.3.1 per the LCP per-chain table). The
+ * buyer signs the Soroban SAC `transfer` whose `to` is that M-address, so the weld is **signature-grade** —
+ * the payer's signature commits the mux id atomically with the transfer.
+ *
+ * **★ recovery.zeroPartyRecoverable = false AND recovery.forwardIndexable = false — deliberately honest.**
+ * A CAP-67 muxed id is exactly **8 bytes**, so only `atrHash[:8]` rides on-chain; the FULL 32-byte atrHash
+ * does NOT fit. From a settlement alone you can recover only the 8-byte prefix, which is not the atrHash —
+ * so the binding CONFIRMS a known atrHash's prefix-8 against the on-chain mux id (`verifyMuxedBinding`), it
+ * does NOT reconstruct the full hash from the chain (that comes from off-chain `extensions.legalContext.info`). Hence
+ * `zeroPartyRecoverable: false` (a party with only the settlement cannot derive the atrHash) and
+ * `forwardIndexable: false` (no native index over mux prefixes; `enumerate` is a best-effort account scan,
+ * `indexing: "account-scan:mux-prefix8"`). The prefix-8 truncation is stated in `finality.note` too.
+ *
+ * **NO `protocol`, and here is precisely what it is neutral OF.** This binding welds into the destination
+ * of a CLASSIC Stellar payment. x402's `exact` scheme for Stellar (read 2026-08-08) is a different flow
+ * entirely: "This spec covers SEP-41-compliant Soroban tokens **only**. Classic Stellar assets are not
+ * supported", and the payment is an `invokeHostFunction` calling `transfer(from, to, amount)` where
+ * "Argument 1 (to): MUST equal `requirements.payTo` exactly".
+ *
+ * A muxed destination cannot appear in that call — there is no classic payment to mux, and an `M…` address
+ * would not equal `payTo` exactly. So a deployment settling through an x402-Stellar facilitator does not
+ * get this carrier. That is a scoping fact, not a defect: the binding has never declared `protocol`, and
+ * the mux weld is correct on the rail it targets. Stated here so the absence is a measured claim rather
+ * than an unexamined default.
+ */
+export const STELLAR_MANIFEST: BindingManifest = {
+  rail: "stellar",
+  pattern: "native-field",
+  nativeField: "cap67-mux-id",
+  recovery: {
+    onChain: true,
+    zeroPartyRecoverable: false,
+    forwardIndexable: false,
+  },
+  assetBinding: "none", // envelope weld — the mux id carries atrHash[:8] only; the asset never appears in the view
+  successGate: "raw-field", // Horizon successful; a txFAILED tx keeps its M-address in the envelope
+  indexing: "account-scan:mux-prefix8",
+  finality: {
+    reversible: false,
+    note: "final on ledger close (Soroban SAC transfer) — no on-rail reversal; only atrHash[:8] rides in the CAP-67 mux id, so settlement alone confirms the prefix-8 match but does NOT recover the full hash (the full atrHash comes from off-chain extensions.legalContext.info); recourse is the record's elected forum (PAY-3/RCS-5), never dispute resolution",
+  },
+  weldGrades: { "cap67-mux": "signature" },
+  lifecycleStates: ["proposed", "settled"],
+};

package/src/mux.ts

@@ -0,0 +1,99 @@
+/**
+ * The CAP-67 muxed-address atrHash codec — the honest heart of the Stellar binding. Ported from the proven
+ * reference mux codec, restricted to the single canonical scheme `mux_id = atrHash[:8]`
+ * (project_stellar_mux_prefix8_audit — the HMAC variant is deliberately NOT ported; it trades the wanted
+ * auditability for unwanted per-seller unlinkability).
+ *
+ * ★ CONFIRM-NOT-RECOVER. A CAP-67 muxed id is exactly 8 bytes. `mux_id = atrHash[:8]` therefore carries
+ * only the FIRST 8 bytes of the 32-byte atrHash on-chain — the full hash does NOT fit. So this module can:
+ *   - DERIVE the 8-byte prefix from a known atrHash (`deriveMuxId`);
+ *   - ENCODE/DECODE a CAP-67 M-address (`encodeMuxedAddress` / `decodeMuxedAddress`), round-tripping the
+ *     8-byte id;
+ *   - CONFIRM that a known atrHash's prefix-8 equals an M-address's on-chain mux id (`verifyMuxedBinding`).
+ * It CANNOT recover the full atrHash from a settlement alone — the settlement holds 8 bytes, not 32. The
+ * full atrHash is obtained off-chain from `extensions.legalContext.info`; the on-chain mux id is the public match
+ * check, not the source of the hash. `recoverMuxIdPrefix8` returns exactly those 8 bytes, labelled as a
+ * prefix — never a `0x…64hex` value that would falsely read as a full atrHash.
+ */
+import { hexToBytes } from "@integraledger/lcp-binding-core";
+import {
+  bytesEqual,
+  canonicalAtrHash,
+  isAtrHash,
+} from "@integraledger/lcp-kernel";
+import { StrKey } from "@stellar/stellar-sdk";
+import { MUX_ID_BYTES } from "./constants.js";
+
+/** Derive the 8-byte mux id from a known atrHash: `mux_id = atrHash[:8]`. Throws on a malformed atrHash
+ *  (fail-fast). Pure — no SDK. */
+export function deriveMuxId(atrHash: string): Uint8Array {
+  return hexToBytes(canonicalAtrHash(atrHash, "deriveMuxId")).slice(
+    0,
+    MUX_ID_BYTES,
+  );
+}
+
+/** Encode a base G-pubkey (StrKey) + 8-byte mux id as a 69-character CAP-67 M-address. Throws on a
+ *  wrong-length mux id (fail-fast). */
+export function encodeMuxedAddress(
+  basePubkey: string,
+  muxId: Uint8Array,
+): string {
+  if (muxId.length !== MUX_ID_BYTES)
+    throw new Error(
+      `encodeMuxedAddress: mux id must be exactly ${MUX_ID_BYTES} bytes, got ${muxId.length}`,
+    );
+  const baseBytes = StrKey.decodeEd25519PublicKey(basePubkey);
+  const combined = new Uint8Array(32 + MUX_ID_BYTES);
+  combined.set(
+    new Uint8Array(
+      baseBytes.buffer,
+      baseBytes.byteOffset,
+      baseBytes.byteLength,
+    ),
+    0,
+  );
+  combined.set(muxId, 32);
+  return StrKey.encodeMed25519PublicKey(Buffer.from(combined));
+}
+
+/** The decoded parts of a CAP-67 M-address: the base G-pubkey and the 8-byte mux id prefix. */
+export interface DecodedMuxedAddress {
+  basePubkey: string;
+  muxId: Uint8Array;
+}
+
+/** Decode a CAP-67 M-address into its base G-pubkey and 8-byte mux id. Returns `null` for anything that is
+ *  not a valid M-address (so a settlement scan skips a non-muxed destination without treating it as an
+ *  error — mirrors the codec's null-vs-throw convention). */
+export function decodeMuxedAddress(mAddr: string): DecodedMuxedAddress | null {
+  if (!StrKey.isValidMed25519PublicKey(mAddr)) return null;
+  const bytes = StrKey.decodeMed25519PublicKey(mAddr);
+  const muxId = new Uint8Array(MUX_ID_BYTES);
+  muxId.set(bytes.subarray(32, 32 + MUX_ID_BYTES));
+  return {
+    basePubkey: StrKey.encodeEd25519PublicKey(bytes.subarray(0, 32)),
+    muxId,
+  };
+}
+
+/** Recover the 8-byte mux id PREFIX from a settlement's CAP-67 M-address. This is the ONLY thing on-chain —
+ *  it is `atrHash[:8]`, NOT the full atrHash. Returned as raw 8 bytes (never a `0x…64hex` value that would
+ *  read as a full hash). `null` if the address is not a valid M-address. */
+export function recoverMuxIdPrefix8(mAddr: string): Uint8Array | null {
+  const decoded = decodeMuxedAddress(mAddr);
+  return decoded === null ? null : decoded.muxId;
+}
+
+/** CONFIRM (not recover): does a known atrHash's prefix-8 equal the mux id carried by `mAddr`? This is the
+ *  primary honest surface — an observer holding the atrHash checks the on-chain destination binds to it.
+ *  `false` for a non-M-address or a malformed atrHash (never throws on those; fail-CLOSED). */
+export function verifyMuxedBinding(inputs: {
+  muxedM: string;
+  atrHash: string;
+}): boolean {
+  if (!isAtrHash(inputs.atrHash)) return false;
+  const onChain = recoverMuxIdPrefix8(inputs.muxedM);
+  if (onChain === null) return false;
+  return bytesEqual(onChain, deriveMuxId(inputs.atrHash));
+}

package/src/stellar-js-xdr.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ambient types for `@stellar/js-xdr` — an UNTYPED transitive of `@stellar/stellar-sdk` (its `lib/xdr.js`
+ * ships no `.d.ts` and no `@types/stellar__js-xdr` exists on the registry). Because `skipLibCheck` is
+ * `false` workspace-wide, the SDK's own `.d.ts` files (`base/index.d.ts`, `base/jsxdr.d.ts`,
+ * `base/numbers/*.d.ts`) fail with TS7016 unless this module is declared. These declarations mirror the
+ * four symbols the SDK re-exports; the adapter never touches js-xdr directly (it uses StrKey /
+ * MuxedAccount / Horizon / typed classes only), so the surface here is intentionally minimal — enough to
+ * satisfy the SDK's re-exports without leaking an `any`-typed value into this package's exports.
+ */
+declare module "@stellar/js-xdr" {
+  export class XdrWriter {
+    constructor(buffer?: Uint8Array);
+    toArray(): Uint8Array;
+  }
+  export class XdrReader {
+    constructor(buffer: Uint8Array);
+    read(count: number): Uint8Array;
+  }
+  /** Base class the SDK's fixed-width XDR integers (Int128/UInt128/Int256/UInt256, XdrLargeInt.int) extend. */
+  export class LargeInt {
+    constructor(...parts: Array<bigint | number | string>);
+    toBigInt(): bigint;
+    toString(): string;
+  }
+  export class UnsignedHyper extends LargeInt {
+    static fromString(value: string): UnsignedHyper;
+  }
+  export class Hyper extends LargeInt {
+    static fromString(value: string): Hyper;
+  }
+}