@myzonerocks/pact 0.1.0

package/src/compliance.ts

@@ -0,0 +1,65 @@
+import type { Money } from "./money.js";
+import type { Quote } from "./message.js";
+
+// KycLimits caps what an identity may transact. An absent perPayment means no cap
+// on that dimension.
+export interface KycLimits {
+  perPayment?: Money;
+}
+
+// KycStatus is what a KycProvider knows about an identity. The kernel uses only
+// the limits to gate quotes; tier and jurisdiction are carried for the host's
+// own policy.
+export interface KycStatus {
+  tier: string;
+  jurisdiction: string;
+  limits: KycLimits;
+}
+
+// KycProvider resolves an identity's compliance standing. It is a seam: the
+// kernel ships a permissive default and holds no policy of its own. A real
+// deployment supplies one before any live-money adapter is enabled.
+export interface KycProvider {
+  status(identity: string): Promise<KycStatus>;
+}
+
+// permissiveKyc imposes no limits, which is only acceptable for test-mode and
+// testnet adapters.
+export const permissiveKyc: KycProvider = {
+  async status(): Promise<KycStatus> {
+    return { tier: "unverified", jurisdiction: "", limits: {} };
+  },
+};
+
+// withinLimits reports whether a quote's source amount is inside an identity's
+// per-payment cap. An absent cap or a currency mismatch is treated as no
+// applicable limit.
+export function withinLimits(status: KycStatus, quote: Quote): boolean {
+  const cap = status.limits.perPayment;
+  if (!cap) return true;
+  try {
+    return quote.srcAmount.cmp(cap) <= 0;
+  } catch {
+    return true;
+  }
+}
+
+// RiskDecision is the outcome of a RiskHook consultation.
+export interface RiskDecision {
+  allow: boolean;
+  reason: string;
+}
+
+// RiskHook is consulted immediately before an authorization is produced. It
+// receives the identity that will sign, so a policy can reason about who is
+// paying, not just what. A veto blocks it. Like KycProvider it is a seam with a
+// permissive default.
+export interface RiskHook {
+  evaluate(identity: string, intent: import("./message.js").Intent, quote: Quote): RiskDecision;
+}
+
+export const allowRisk: RiskHook = {
+  evaluate(): RiskDecision {
+    return { allow: true, reason: "" };
+  },
+};

package/src/crypto.ts

@@ -0,0 +1,68 @@
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  sign as nodeSign,
+  verify as nodeVerify,
+  type KeyObject,
+} from "node:crypto";
+
+// SHA-256 of a byte string. Every message hash and receipt commitment flows
+// through it.
+export function sha256(data: Uint8Array): Uint8Array {
+  return new Uint8Array(createHash("sha256").update(data).digest());
+}
+
+// The fixed DER prefixes that wrap a raw 32-byte Ed25519 seed or public key so
+// the platform key APIs will import them. The seed becomes a PKCS8 private key;
+// the public key becomes an SPKI public key.
+const pkcs8SeedPrefix = Buffer.from("302e020100300506032b657004220420", "hex");
+const spkiPublicPrefix = Buffer.from("302a300506032b6570032100", "hex");
+
+export interface Ed25519KeyPair {
+  privateKey: KeyObject;
+  publicKey: Uint8Array;
+}
+
+// ed25519KeyFromSeed derives a signing key pair from a 32-byte seed. Ed25519 is
+// deterministic, so a given seed and message always yield the same signature,
+// which is what lets the cross-language vectors pin an exact signature.
+export function ed25519KeyFromSeed(seed: Uint8Array): Ed25519KeyPair {
+  if (seed.length !== 32) {
+    throw new Error("pact: ed25519 seed must be 32 bytes");
+  }
+  const der = Buffer.concat([pkcs8SeedPrefix, Buffer.from(seed)]);
+  const privateKey = createPrivateKey({ key: der, format: "der", type: "pkcs8" });
+  const spki = createPublicKey(privateKey).export({ format: "der", type: "spki" }) as Buffer;
+  return { privateKey, publicKey: new Uint8Array(spki.subarray(spki.length - 32)) };
+}
+
+export function ed25519Sign(privateKey: KeyObject, message: Uint8Array): Uint8Array {
+  return new Uint8Array(nodeSign(null, Buffer.from(message), privateKey));
+}
+
+export function ed25519Verify(publicKeyRaw: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean {
+  if (publicKeyRaw.length !== 32) {
+    return false;
+  }
+  const spki = Buffer.concat([spkiPublicPrefix, Buffer.from(publicKeyRaw)]);
+  const publicKey = createPublicKey({ key: spki, format: "der", type: "spki" });
+  return nodeVerify(null, Buffer.from(message), publicKey, Buffer.from(signature));
+}
+
+// toHex and fromHex render byte strings for the wire and for test vectors.
+export function toHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("hex");
+}
+
+export function fromHex(hex: string): Uint8Array {
+  return new Uint8Array(Buffer.from(hex, "hex"));
+}
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

package/src/fake.ts

@@ -0,0 +1,96 @@
+import { State } from "./state.js";
+import { RefundKind } from "./adapter.js";
+import type { Money } from "./money.js";
+import type { Quote, Authorization, Settlement } from "./message.js";
+import type { RateSource, EscrowVault } from "./bridge.js";
+import type {
+  PayInLeg,
+  PayOutLeg,
+  PayInCapabilities,
+  PayOutCapabilities,
+  CollectResult,
+  DisburseResult,
+} from "./leg.js";
+
+// FakeLeg is a deterministic, in-memory pay-in and pay-out leg. It settles
+// instantly with no network and implements both sides so a test can build a
+// direct corridor from one leg or a bridged corridor from two. failPayout makes
+// its disburse fail so a test can exercise the escrow-unwind path.
+export class FakeLeg implements PayInLeg, PayOutLeg {
+  failPayout = false;
+
+  constructor(
+    readonly id: string,
+    private readonly rail: string,
+    private readonly currency: string,
+    private readonly ids: () => string,
+  ) {}
+
+  payInCapabilities(): PayInCapabilities {
+    return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.Full };
+  }
+
+  // collect takes the payer's funds. received is the net the bridge converts —
+  // the source the payer paid less the corridor fees.
+  async collect(_intentId: string, quote: Quote, _auth: Authorization, _deliverTo: string): Promise<CollectResult> {
+    return { providerRef: this.ids(), received: quote.srcAmount.sub(quote.fees) };
+  }
+
+  async refundIn(intentId: string, _kind: RefundKind, reason: string): Promise<Settlement> {
+    return this.terminal(intentId, reason);
+  }
+
+  payOutCapabilities(): PayOutCapabilities {
+    return { rails: [this.rail], currencies: [this.currency], reversible: false };
+  }
+
+  async disburse(_intentId: string, _quote: Quote, _recipientRef: string): Promise<DisburseResult> {
+    if (this.failPayout) {
+      throw new Error("fake: payout failed");
+    }
+    return { providerRef: this.ids() };
+  }
+
+  async reverseOut(intentId: string, reason: string): Promise<Settlement> {
+    return this.terminal(intentId, reason);
+  }
+
+  private terminal(intentId: string, reason: string): Settlement {
+    return {
+      intentId,
+      state: State.Refunded,
+      adapterId: this.id,
+      providerTxRef: this.ids(),
+      onchainTxHash: "",
+      receiptHash: new Uint8Array(0),
+      reason,
+      settledAt: 0,
+    };
+  }
+}
+
+// FakeRates is an in-memory rate source keyed by "FROM:TO", standing in for a
+// price feed so a bridge can be tested without a live market.
+export class FakeRates implements RateSource {
+  constructor(private readonly table: Record<string, string>) {}
+
+  async rate(from: string, to: string): Promise<string> {
+    const rate = this.table[`${from}:${to}`];
+    if (rate === undefined) {
+      throw new Error(`fake: no rate for ${from}:${to}`);
+    }
+    return rate;
+  }
+}
+
+// FakeVault is an in-memory escrow that records holds and releases, standing in
+// for the custody a real bridge relies on.
+export class FakeVault implements EscrowVault {
+  async hold(intentId: string, _amount: Money): Promise<string> {
+    return `escrow-${intentId}`;
+  }
+
+  async release(_intentId: string): Promise<void> {
+    // Nothing to release in memory.
+  }
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+export { ID, VERSION, domain, DEFAULT_SKEW_MILLIS } from "./protocol.js";
+export { Money } from "./money.js";
+export { State, stateName, canTransition, isTerminal, TransitionError } from "./state.js";
+export { CanonicalWriter, hashPreimage } from "./canonical.js";
+export {
+  type Intent,
+  type Quote,
+  type Authorization,
+  type Settlement,
+  BRIDGE_PASSTHROUGH,
+  intentPreimage,
+  intentHash,
+  quotePreimage,
+  quoteHash,
+  isDirect,
+  signingPreimage,
+  authorizationHash,
+  receiptHash,
+  corridorReceipt,
+} from "./message.js";
+export {
+  type Signer,
+  type Verifier,
+  authorize,
+  verifyAuthorization,
+  Ed25519Signer,
+  Ed25519Verifier,
+  BadSignatureError,
+} from "./signing.js";
+export { RefundKind, type AdapterEvent, type WebhookParser } from "./adapter.js";
+export {
+  railInList,
+  type PayInLeg,
+  type PayOutLeg,
+  type PayInCapabilities,
+  type PayOutCapabilities,
+  type CollectResult,
+  type DisburseResult,
+} from "./leg.js";
+export {
+  BRIDGE_USDC,
+  PassThroughBridge,
+  UsdcBridge,
+  applyRate,
+  applyInverseRate,
+  parseRate,
+  type Bridge,
+  type BridgeQuote,
+  type ConvertResult,
+  type RateSource,
+  type EscrowVault,
+} from "./bridge.js";
+export {
+  type KycProvider,
+  type KycStatus,
+  type KycLimits,
+  type RiskHook,
+  type RiskDecision,
+  permissiveKyc,
+  allowRisk,
+  withinLimits,
+} from "./compliance.js";
+export { PolicyKind, type Policy, route, isExpired, NoQuoteError } from "./router.js";
+export {
+  MemoryLedger,
+  eventReceipt,
+  chainLeaf,
+  IdempotencyConflictError,
+  type Ledger,
+  type LedgerEvent,
+  type Transition,
+} from "./ledger.js";
+export {
+  Client,
+  type ClientConfig,
+  type IntentSpec,
+  type Funding,
+  type Clock,
+  type IdGen,
+  systemClock,
+  randomId,
+  recipientDestination,
+} from "./client.js";
+export { FakeLeg, FakeRates, FakeVault } from "./fake.js";
+export {
+  WireKind,
+  type WireMessage,
+  encodeIntent,
+  encodeQuote,
+  encodeAuthorization,
+  encodeSettlement,
+  encodeMessage,
+  decodeMessage,
+  decodeIntent,
+  decodeQuote,
+  decodeAuthorization,
+  decodeSettlement,
+} from "./wire.js";
+export {
+  PAYLOAD_VERSION,
+  encodePayload,
+  decodePayload,
+  isPayload,
+  NotPayloadError,
+  UnsupportedPayloadVersionError,
+} from "./payload.js";

package/src/ledger.ts

@@ -0,0 +1,145 @@
+import { State, stateName, canTransition, TransitionError } from "./state.js";
+import { CanonicalWriter, hashPreimage } from "./canonical.js";
+import { domain } from "./protocol.js";
+import { bytesEqual } from "./crypto.js";
+import type { Intent, Quote, Authorization, Settlement } from "./message.js";
+import type { CollectResult } from "./leg.js";
+import type { ConvertResult } from "./bridge.js";
+
+// LedgerEvent is one immutable step in an intent's history. State is never
+// mutated in place; the current state is the last event's state, and the whole
+// history folds into a single Merkle head.
+export interface LedgerEvent {
+  seq: number;
+  intentId: string;
+  state: State;
+  payloadHash: Uint8Array;
+  receipt: Uint8Array;
+  leaf: Uint8Array;
+  intent?: Intent;
+  quote?: Quote;
+  authorization?: Authorization;
+  settlement?: Settlement;
+  // collect and bridge persist the intermediate results a corridor needs to
+  // resume: what the pay-in leg collected, and what the bridge converted. They
+  // let settlement be driven forward by later provider events without holding
+  // anything open between them.
+  collect?: CollectResult;
+  bridge?: ConvertResult;
+}
+
+// Transition is a proposed append: the target state, the hash of the causing
+// message, and the message itself for durable storage.
+export interface Transition {
+  intentId: string;
+  to: State;
+  payloadHash: Uint8Array;
+  intent?: Intent;
+  quote?: Quote;
+  authorization?: Authorization;
+  settlement?: Settlement;
+  collect?: CollectResult;
+  bridge?: ConvertResult;
+}
+
+export class IdempotencyConflictError extends Error {
+  constructor() {
+    super("pact: idempotency conflict: step already recorded with a different payload");
+    this.name = "IdempotencyConflictError";
+  }
+}
+
+// Ledger is the append-only store of payment history. The kernel ships an
+// in-memory reference; durable backends implement the same interface and must
+// preserve the same event order, receipts, and Merkle head.
+export interface Ledger {
+  apply(t: Transition): LedgerEvent;
+  state(intentId: string): State;
+  events(intentId: string): LedgerEvent[];
+  head(intentId: string): Uint8Array | undefined;
+}
+
+const zeroLeaf = new Uint8Array(32);
+
+// MemoryLedger is the in-memory reference ledger.
+export class MemoryLedger implements Ledger {
+  private readonly byIntent = new Map<string, LedgerEvent[]>();
+
+  apply(t: Transition): LedgerEvent {
+    const history = this.byIntent.get(t.intentId) ?? [];
+
+    // A repeat of the same step is a no-op returning the first result; the same
+    // step with a different payload is a conflict.
+    for (const e of history) {
+      if (e.state === t.to) {
+        if (bytesEqual(e.payloadHash, t.payloadHash)) return e;
+        throw new IdempotencyConflictError();
+      }
+    }
+
+    const current = history.length > 0 ? (history[history.length - 1] as LedgerEvent).state : State.Unspecified;
+    if (!canTransition(current, t.to)) {
+      throw new TransitionError(current, t.to);
+    }
+
+    const prevLeaf = history.length > 0 ? (history[history.length - 1] as LedgerEvent).leaf : zeroLeaf;
+    const seq = history.length + 1;
+    const receipt = eventReceipt(seq, t.intentId, t.to, t.payloadHash);
+    const leaf = chainLeaf(prevLeaf, receipt);
+
+    const event: LedgerEvent = {
+      seq,
+      intentId: t.intentId,
+      state: t.to,
+      payloadHash: t.payloadHash.slice(),
+      receipt,
+      leaf,
+      ...(t.intent ? { intent: t.intent } : {}),
+      ...(t.quote ? { quote: t.quote } : {}),
+      ...(t.authorization ? { authorization: t.authorization } : {}),
+      ...(t.settlement ? { settlement: t.settlement } : {}),
+      ...(t.collect ? { collect: t.collect } : {}),
+      ...(t.bridge ? { bridge: t.bridge } : {}),
+    };
+    this.byIntent.set(t.intentId, [...history, event]);
+    return event;
+  }
+
+  state(intentId: string): State {
+    const history = this.byIntent.get(intentId);
+    if (!history || history.length === 0) return State.Unspecified;
+    return (history[history.length - 1] as LedgerEvent).state;
+  }
+
+  events(intentId: string): LedgerEvent[] {
+    return [...(this.byIntent.get(intentId) ?? [])];
+  }
+
+  head(intentId: string): Uint8Array | undefined {
+    const history = this.byIntent.get(intentId);
+    if (!history || history.length === 0) return undefined;
+    return (history[history.length - 1] as LedgerEvent).leaf;
+  }
+}
+
+// eventReceipt commits to an event's identity independent of the Merkle chaining,
+// so a single event can be shown and checked on its own.
+export function eventReceipt(seq: number, intentId: string, state: State, payloadHash: Uint8Array): Uint8Array {
+  return hashPreimage(
+    new CanonicalWriter()
+      .str(domain("event"))
+      .u64(seq)
+      .str(intentId)
+      .str(stateName[state])
+      .bytes(payloadHash)
+      .preimage(),
+  );
+}
+
+// chainLeaf folds one event's receipt into the running Merkle head.
+export function chainLeaf(prevLeaf: Uint8Array, receipt: Uint8Array): Uint8Array {
+  const joined = new Uint8Array(prevLeaf.length + receipt.length);
+  joined.set(prevLeaf, 0);
+  joined.set(receipt, prevLeaf.length);
+  return hashPreimage(joined);
+}

package/src/leg.ts

@@ -0,0 +1,65 @@
+import type { Money } from "./money.js";
+import type { Quote, Authorization, Settlement } from "./message.js";
+import type { RefundKind } from "./adapter.js";
+
+// A corridor is built from two legs. A provider adapter implements the legs it
+// can serve: a pay-in leg collects from the payer, a pay-out leg disburses to
+// the recipient. Many providers serve only one; some serve both. The kernel
+// composes them and never holds funds itself.
+
+// PayInCapabilities describes what a pay-in leg can collect. Methods lists the
+// funding surfaces the leg exposes without a separate adapter — a card leg via a
+// processor exposes card plus the wallets that ride on it. Methods are
+// informational; routing is on the rail.
+export interface PayInCapabilities {
+  rails: string[];
+  currencies: string[];
+  methods?: string[];
+  refunds: RefundKind;
+}
+
+// CollectResult is what a pay-in leg returns once it has taken the payer's
+// funds. received is the amount actually collected, which the bridge converts.
+export interface CollectResult {
+  providerRef: string;
+  received: Money;
+}
+
+// PayInLeg collects the payer's funds in the source currency. deliverTo is where
+// the collected funds should land: the recipient's handle for a direct corridor,
+// or the bridge escrow for a bridged one. The kernel computes it, so the leg does
+// not need to know which corridor shape it is serving.
+export interface PayInLeg {
+  id: string;
+  payInCapabilities(): PayInCapabilities;
+  collect(intentId: string, quote: Quote, auth: Authorization, deliverTo: string): Promise<CollectResult>;
+  refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
+}
+
+// PayOutCapabilities describes what a pay-out leg can deliver. reversible reports
+// whether a completed payout can be pulled back; an irreversible rail answers a
+// refund with a counter-transfer, never a reversal.
+export interface PayOutCapabilities {
+  rails: string[];
+  currencies: string[];
+  reversible: boolean;
+}
+
+// DisburseResult is what a pay-out leg returns once it has sent funds to the
+// recipient.
+export interface DisburseResult {
+  providerRef: string;
+}
+
+// PayOutLeg delivers funds to the recipient in the destination currency.
+export interface PayOutLeg {
+  id: string;
+  payOutCapabilities(): PayOutCapabilities;
+  disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult>;
+  reverseOut(intentId: string, reason: string): Promise<Settlement>;
+}
+
+// railInList reports whether a set of rails contains the requested rail.
+export function railInList(rails: string[], rail: string): boolean {
+  return rails.includes(rail);
+}