@myzonerocks/pact 0.1.0

package/src/message.ts

@@ -0,0 +1,178 @@
+import { Money } from "./money.js";
+import { State, stateName } from "./state.js";
+import { CanonicalWriter, hashPreimage } from "./canonical.js";
+import { domain } from "./protocol.js";
+
+// Intent is a payment request minted by the sender. senderRef and recipientRef
+// are opaque host-scoped handles, never personally identifying data on the wire.
+export interface Intent {
+  id: string;
+  senderRef: string;
+  recipientRef: string;
+  amount: Money;
+  memo: string;
+  expiresAt: number;
+  allowedRails: string[];
+  metadata: Record<string, string>;
+}
+
+export function intentPreimage(i: Intent): Uint8Array {
+  return new CanonicalWriter()
+    .str(domain("intent"))
+    .str(i.id)
+    .str(i.senderRef)
+    .str(i.recipientRef)
+    .money(i.amount)
+    .str(i.memo)
+    .u64(i.expiresAt)
+    .list(i.allowedRails)
+    .stringMap(i.metadata)
+    .preimage();
+}
+
+export function intentHash(i: Intent): Uint8Array {
+  return hashPreimage(intentPreimage(i));
+}
+
+// The bridge that moves value unchanged when the payer and recipient already
+// share a currency. Its identifier is a stable wire value carried in a quote.
+export const BRIDGE_PASSTHROUGH = "passthrough";
+
+// Quote is a corridor: one offer to move value from the payer to the recipient
+// through a pay-in leg, a bridge, and a pay-out leg. A direct payment is the case
+// where the pay-in and pay-out are the same provider, the bridge is pass-through,
+// and src and dst share a currency. srcAmount is what the payer pays in X;
+// dstAmount is what the recipient receives in Y.
+export interface Quote {
+  id: string;
+  intentId: string;
+  payInAdapterId: string;
+  payInRail: string;
+  payOutAdapterId: string;
+  payOutRail: string;
+  bridgeId: string;
+  srcAmount: Money;
+  dstAmount: Money;
+  fees: Money; // total across the legs and bridge, in X
+  fxRate: string; // decimal ASCII, Y per X; "1" for a direct corridor
+  expiresAt: number;
+  providerQuoteRef: string;
+  latencyEstimateMs: number;
+}
+
+export function quotePreimage(q: Quote): Uint8Array {
+  return new CanonicalWriter()
+    .str(domain("quote"))
+    .str(q.id)
+    .str(q.intentId)
+    .str(q.payInAdapterId)
+    .str(q.payInRail)
+    .str(q.payOutAdapterId)
+    .str(q.payOutRail)
+    .str(q.bridgeId)
+    .money(q.srcAmount)
+    .money(q.dstAmount)
+    .money(q.fees)
+    .str(q.fxRate)
+    .u64(q.expiresAt)
+    .str(q.providerQuoteRef)
+    .u64(q.latencyEstimateMs)
+    .preimage();
+}
+
+export function quoteHash(q: Quote): Uint8Array {
+  return hashPreimage(quotePreimage(q));
+}
+
+// isDirect reports whether a corridor settles in one phase: the same provider
+// serves both legs and the bridge is pass-through.
+export function isDirect(q: Quote): boolean {
+  return q.payInAdapterId === q.payOutAdapterId && q.bridgeId === BRIDGE_PASSTHROUGH;
+}
+
+// Authorization is the sender's signed commitment to exactly one quote. The
+// signature covers a preimage binding both the intent hash and the quote hash,
+// so it cannot be replayed against a different intent or quote.
+export interface Authorization {
+  intentId: string;
+  quoteId: string;
+  signerIdentity: string;
+  signedAt: number;
+  signature: Uint8Array;
+}
+
+// signingPreimage returns the bytes an authorization signs over.
+export function signingPreimage(
+  intentHashBytes: Uint8Array,
+  quoteHashBytes: Uint8Array,
+  signerIdentity: string,
+  signedAt: number,
+): Uint8Array {
+  return new CanonicalWriter()
+    .str(domain("authorize"))
+    .bytes(intentHashBytes)
+    .bytes(quoteHashBytes)
+    .str(signerIdentity)
+    .u64(signedAt)
+    .preimage();
+}
+
+export function authorizationHash(
+  intentHashBytes: Uint8Array,
+  quoteHashBytes: Uint8Array,
+  signerIdentity: string,
+  signedAt: number,
+): Uint8Array {
+  return hashPreimage(signingPreimage(intentHashBytes, quoteHashBytes, signerIdentity, signedAt));
+}
+
+// Settlement is the terminal or refund outcome for an intent.
+export interface Settlement {
+  intentId: string;
+  state: State;
+  adapterId: string;
+  providerTxRef: string;
+  onchainTxHash: string;
+  receiptHash: Uint8Array;
+  reason: string;
+  settledAt: number;
+}
+
+// receiptHash derives a settlement's receipt commitment from the authorization
+// hash it settles, the provider's transaction reference, and the resulting
+// state. Revealing it plus a ledger inclusion proof lets a recipient prove a
+// settlement without exposing any surrounding conversation.
+export function receiptHash(authHash: Uint8Array, providerTxRef: string, state: State): Uint8Array {
+  return hashPreimage(
+    new CanonicalWriter()
+      .str(domain("receipt"))
+      .bytes(authHash)
+      .str(providerTxRef)
+      .str(stateName[state])
+      .preimage(),
+  );
+}
+
+// corridorReceipt binds both legs of a bridged corridor and the FX rate into one
+// commitment, so the payer can prove they funded X and the recipient can prove
+// they received Y as a single transaction, without revealing anything else.
+export function corridorReceipt(
+  authHash: Uint8Array,
+  payInProviderRef: string,
+  payOutProviderRef: string,
+  fxRate: string,
+  bridgeReceiptRef: string,
+  state: State,
+): Uint8Array {
+  return hashPreimage(
+    new CanonicalWriter()
+      .str(domain("corridor"))
+      .bytes(authHash)
+      .str(payInProviderRef)
+      .str(payOutProviderRef)
+      .str(fxRate)
+      .str(bridgeReceiptRef)
+      .str(stateName[state])
+      .preimage(),
+  );
+}

package/src/money.ts

@@ -0,0 +1,87 @@
+// Money is an exact count of minor units in a single currency. The amount is a
+// bigint, never a number: an 18-decimal token counted in its smallest unit
+// overflows a 64-bit integer at roughly nine whole tokens, and floating point
+// has no place near money.
+const currencyPattern = /^[A-Z0-9]{1,16}$/;
+const maxExponent = 30;
+
+export class Money {
+  private constructor(
+    readonly currency: string,
+    readonly exponent: number,
+    private readonly amount: bigint,
+  ) {}
+
+  static create(currency: string, exponent: number, amount: bigint): Money {
+    if (!currencyPattern.test(currency)) {
+      throw new Error("pact: currency must match [A-Z0-9]{1,16}");
+    }
+    if (!Number.isInteger(exponent) || exponent < 0 || exponent > maxExponent) {
+      throw new Error(`pact: exponent must be 0..${maxExponent}`);
+    }
+    if (amount < 0n) {
+      throw new Error("pact: amount must be non-negative");
+    }
+    return new Money(currency, exponent, amount);
+  }
+
+  // parse builds Money from a decimal-ASCII minor-unit string, the form used on
+  // the wire.
+  static parse(currency: string, exponent: number, minor: string): Money {
+    if (!/^\d+$/.test(minor)) {
+      throw new Error(`pact: ${minor} is not a base-10 integer`);
+    }
+    return Money.create(currency, exponent, BigInt(minor));
+  }
+
+  // minor renders the amount as canonical decimal ASCII: no leading zeros, "0"
+  // for zero. This is the exact string the canonical writer and the wire use.
+  minor(): string {
+    return this.amount.toString();
+  }
+
+  value(): bigint {
+    return this.amount;
+  }
+
+  private sameKind(other: Money): boolean {
+    return this.currency === other.currency && this.exponent === other.exponent;
+  }
+
+  add(other: Money): Money {
+    if (!this.sameKind(other)) {
+      throw new Error("pact: money operands differ in currency or exponent");
+    }
+    return new Money(this.currency, this.exponent, this.amount + other.amount);
+  }
+
+  // sub errors when the result would be negative: Money has no negative range,
+  // and a refund is a settlement, not a negative sum.
+  sub(other: Money): Money {
+    if (!this.sameKind(other)) {
+      throw new Error("pact: money operands differ in currency or exponent");
+    }
+    const diff = this.amount - other.amount;
+    if (diff < 0n) {
+      throw new Error("pact: amount must be non-negative");
+    }
+    return new Money(this.currency, this.exponent, diff);
+  }
+
+  cmp(other: Money): number {
+    if (!this.sameKind(other)) {
+      throw new Error("pact: money operands differ in currency or exponent");
+    }
+    if (this.amount < other.amount) return -1;
+    if (this.amount > other.amount) return 1;
+    return 0;
+  }
+
+  isZero(): boolean {
+    return this.amount === 0n;
+  }
+
+  toString(): string {
+    return `${this.minor()} ${this.currency}/${this.exponent}`;
+  }
+}

package/src/payload.ts

@@ -0,0 +1,58 @@
+import { ID } from "./protocol.js";
+import { encodeMessage, decodeMessage, type WireMessage } from "./wire.js";
+
+// A payload is how a payment message rides inside a host's own envelope — a chat
+// message, a queue entry, any transport. It wraps a wire frame with a small
+// self-identifying header so a receiver can tell a PACT payload apart from other
+// envelope content and reject a version it does not understand. The host carries
+// opaque bytes and stays oblivious to the message inside.
+
+const payloadMagic = new TextEncoder().encode(ID);
+
+// PAYLOAD_VERSION is the framing version, independent of the wire version, so the
+// envelope format can evolve without breaking a decoder.
+export const PAYLOAD_VERSION = 1;
+
+export class NotPayloadError extends Error {
+  constructor() {
+    super("pact: not a pact payload");
+    this.name = "NotPayloadError";
+  }
+}
+
+export class UnsupportedPayloadVersionError extends Error {
+  constructor(version: number) {
+    super(`pact: unsupported payload version ${version}`);
+    this.name = "UnsupportedPayloadVersionError";
+  }
+}
+
+export function encodePayload(msg: WireMessage): Uint8Array {
+  const frame = encodeMessage(msg);
+  const out = new Uint8Array(payloadMagic.length + 1 + frame.length);
+  out.set(payloadMagic, 0);
+  out[payloadMagic.length] = PAYLOAD_VERSION;
+  out.set(frame, payloadMagic.length + 1);
+  return out;
+}
+
+// isPayload reports whether bytes carry the PACT payload header, so an envelope
+// decoder can route them to decodePayload without attempting a full parse.
+export function isPayload(bytes: Uint8Array): boolean {
+  if (bytes.length <= payloadMagic.length) return false;
+  for (let i = 0; i < payloadMagic.length; i++) {
+    if (bytes[i] !== payloadMagic[i]) return false;
+  }
+  return true;
+}
+
+export function decodePayload(bytes: Uint8Array): WireMessage {
+  if (!isPayload(bytes)) {
+    throw new NotPayloadError();
+  }
+  const version = bytes[payloadMagic.length] as number;
+  if (version !== PAYLOAD_VERSION) {
+    throw new UnsupportedPayloadVersionError(version);
+  }
+  return decodeMessage(bytes.subarray(payloadMagic.length + 1));
+}

package/src/policy.ts

@@ -0,0 +1,110 @@
+import { Money } from "./money.js";
+import type { Intent, Quote } from "./message.js";
+import type { KycProvider, KycStatus, RiskHook, RiskDecision } from "./compliance.js";
+
+// This is an optional reference implementation of the compliance seams. The
+// kernel ships no policy of its own; an adopter either wires this in or supplies
+// their own KycProvider and RiskHook. Nothing here is required by the protocol,
+// and everything is configurable so it can be replaced without touching the
+// kernel.
+
+// Tier is a verification level with the limits and reach it grants. An adopter
+// defines the tiers their jurisdiction and licensing require.
+export interface Tier {
+  name: string;
+  jurisdiction: string;
+  perPayment?: Money; // absent means no per-payment cap
+  windowSpend?: Money; // absent means no rolling-window cap
+  allowedRails?: string[]; // absent or empty means every rail is allowed
+}
+
+function railAllowed(tier: Tier, rail: string): boolean {
+  if (!tier.allowedRails || tier.allowedRails.length === 0) return true;
+  return tier.allowedRails.includes(rail);
+}
+
+// TieredKyc resolves an identity to its tier and reports the per-payment limit the
+// kernel's router already enforces. Identities with no assigned tier fall to the
+// configured fallback tier.
+export class TieredKyc implements KycProvider {
+  private readonly tiers: Map<string, Tier>;
+
+  constructor(
+    tiers: Tier[],
+    private readonly assigned: Record<string, string>,
+    private readonly fallback: Tier,
+  ) {
+    this.tiers = new Map(tiers.map((t) => [t.name, t]));
+  }
+
+  // tierFor returns the tier governing an identity.
+  tierFor(identity: string): Tier {
+    const name = this.assigned[identity];
+    if (name !== undefined) {
+      const tier = this.tiers.get(name);
+      if (tier) return tier;
+    }
+    return this.fallback;
+  }
+
+  async status(identity: string): Promise<KycStatus> {
+    const tier = this.tierFor(identity);
+    return {
+      tier: tier.name,
+      jurisdiction: tier.jurisdiction,
+      limits: tier.perPayment ? { perPayment: tier.perPayment } : {},
+    };
+  }
+}
+
+interface SpendEntry {
+  atMillis: number;
+  amount: Money;
+}
+
+// WindowRisk enforces the per-tier rail allow-list and a rolling-window spend
+// cap. It owns its own spend ledger, so the state a compliance decision needs
+// never leaks into the kernel.
+export class WindowRisk implements RiskHook {
+  private readonly spend = new Map<string, SpendEntry[]>();
+
+  constructor(
+    private readonly kyc: TieredKyc,
+    private readonly windowMillis: number,
+    private readonly now: () => number,
+  ) {}
+
+  // evaluate vetoes a payment whose rail the tier forbids, or whose source amount
+  // would push the identity's spend over the window cap. An allowed payment is
+  // recorded so it counts against the window for the next one.
+  evaluate(identity: string, _intent: Intent, quote: Quote): RiskDecision {
+    const tier = this.kyc.tierFor(identity);
+    if (!railAllowed(tier, quote.payInRail) || !railAllowed(tier, quote.payOutRail)) {
+      return { allow: false, reason: "rail not permitted for this tier" };
+    }
+    if (!tier.windowSpend) {
+      return { allow: true, reason: "" };
+    }
+
+    const now = this.now();
+    const horizon = now - this.windowMillis;
+    const kept = (this.spend.get(identity) ?? []).filter((e) => e.atMillis > horizon);
+
+    let total = Money.create(tier.windowSpend.currency, tier.windowSpend.exponent, 0n);
+    try {
+      for (const e of kept) total = total.add(e.amount);
+      const projected = total.add(quote.srcAmount);
+      if (projected.cmp(tier.windowSpend) > 0) {
+        this.spend.set(identity, kept);
+        return { allow: false, reason: "payment exceeds the rolling spend limit" };
+      }
+    } catch {
+      this.spend.set(identity, kept);
+      return { allow: false, reason: "payment currency differs from the window cap" };
+    }
+
+    kept.push({ atMillis: now, amount: quote.srcAmount });
+    this.spend.set(identity, kept);
+    return { allow: true, reason: "" };
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,19 @@
+// ID is the stable protocol identifier. It is a technical constant, not a brand:
+// it appears only inside domain-separation tags and is never localized or
+// rebranded. Changing it is a breaking wire migration.
+export const ID = "pact";
+
+// VERSION is the wire version. It composes with ID into the domain prefix every
+// signed preimage begins with.
+export const VERSION = "1";
+
+const domainPrefix = `${ID}/${VERSION}/`;
+
+// domain builds the full domain tag for a message kind, e.g. "pact/1/intent".
+export function domain(kind: string): string {
+  return domainPrefix + kind;
+}
+
+// DEFAULT_SKEW_MILLIS is the tolerated clock difference when deciding whether an
+// intent or quote has expired.
+export const DEFAULT_SKEW_MILLIS = 120_000;

package/src/router.ts

@@ -0,0 +1,97 @@
+import type { Quote } from "./message.js";
+import type { KycStatus } from "./compliance.js";
+import { withinLimits } from "./compliance.js";
+
+// PolicyKind names how the router chooses among competing quotes.
+export enum PolicyKind {
+  Cheapest = 0,
+  Fastest,
+  PreferredRail,
+}
+
+// Policy configures router selection. It is plain data so the client and the
+// server can be handed the identical policy and reach the identical choice.
+export interface Policy {
+  kind: PolicyKind;
+  preferredRails?: string[];
+}
+
+export class NoQuoteError extends Error {
+  constructor(reason: string) {
+    super(`pact: no eligible quote: ${reason}`);
+    this.name = "NoQuoteError";
+  }
+}
+
+export function isExpired(deadline: number, now: number, skew: number): boolean {
+  if (deadline === 0) return false;
+  return deadline + skew <= now;
+}
+
+// route selects one quote deterministically. It first discards quotes that are
+// expired against now or that exceed the identity's KYC limit, then ranks the
+// survivors by the policy. Ties break by pay-in adapter, then pay-out adapter,
+// then quote id, so the choice is total and stable and never depends on input
+// order or randomness.
+export function route(quotes: Quote[], policy: Policy, kyc: KycStatus, now: number, skew: number): Quote {
+  const eligible = quotes.filter((q) => !isExpired(q.expiresAt, now, skew) && withinLimits(kyc, q));
+  if (eligible.length === 0) {
+    throw new NoQuoteError("all quotes expired or over limit");
+  }
+  const rank = rankFn(policy);
+  eligible.sort((a, b) => {
+    const primary = rank(a, b);
+    if (primary !== 0) return primary;
+    if (a.payInAdapterId !== b.payInAdapterId) return a.payInAdapterId < b.payInAdapterId ? -1 : 1;
+    if (a.payOutAdapterId !== b.payOutAdapterId) return a.payOutAdapterId < b.payOutAdapterId ? -1 : 1;
+    if (a.id !== b.id) return a.id < b.id ? -1 : 1;
+    return 0;
+  });
+  return eligible[0] as Quote;
+}
+
+function rankFn(policy: Policy): (a: Quote, b: Quote) => number {
+  switch (policy.kind) {
+    case PolicyKind.Fastest:
+      return (a, b) => cmpNumber(a.latencyEstimateMs, b.latencyEstimateMs);
+    case PolicyKind.PreferredRail: {
+      const rank = railRank(policy.preferredRails ?? []);
+      return (a, b) => {
+        const byRail = cmpNumber(rank(a.payOutRail), rank(b.payOutRail));
+        return byRail !== 0 ? byRail : cmpMoney(a, b);
+      };
+    }
+    default:
+      return (a, b) => {
+        const bySrc = cmpMoney(a, b);
+        if (bySrc !== 0) return bySrc;
+        return safeCmp(a.fees, b.fees);
+      };
+  }
+}
+
+function railRank(preferred: string[]): (rail: string) => number {
+  const index = new Map<string, number>();
+  preferred.forEach((rail, i) => index.set(rail, i));
+  const unranked = preferred.length;
+  return (rail) => index.get(rail) ?? unranked;
+}
+
+function cmpNumber(a: number, b: number): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// cmpMoney orders two quotes by source amount. Amounts in different currencies
+// are treated as incomparable and reported equal, deferring to the tie-break so
+// the router never throws on a mixed-currency quote set.
+function cmpMoney(a: Quote, b: Quote): number {
+  return safeCmp(a.srcAmount, b.srcAmount);
+}
+
+function safeCmp(a: { cmp(o: typeof a): number }, b: typeof a): number {
+  try {
+    return a.cmp(b);
+  } catch {
+    return 0;
+  }
+}

package/src/signing.ts

@@ -0,0 +1,92 @@
+import type { Intent, Quote, Authorization } from "./message.js";
+import { intentHash, quoteHash, signingPreimage } from "./message.js";
+import { ed25519KeyFromSeed, ed25519Sign, ed25519Verify } from "./crypto.js";
+import type { KeyObject } from "node:crypto";
+
+// Signer produces a signature over a preimage for an identity. The host supplies
+// it, reusing whatever key already backs the identity. The kernel never holds or
+// sees private key material.
+export interface Signer {
+  identity(): string;
+  sign(preimage: Uint8Array): Uint8Array;
+}
+
+// Verifier checks a signature over a preimage against a claimed identity. It is
+// the host-supplied counterpart to Signer, keeping the kernel scheme-agnostic.
+export interface Verifier {
+  verify(identity: string, preimage: Uint8Array, signature: Uint8Array): boolean;
+}
+
+export class BadSignatureError extends Error {
+  constructor() {
+    super("pact: signature does not verify");
+    this.name = "BadSignatureError";
+  }
+}
+
+// authorize builds and signs an authorization committing a sender to one quote
+// for one intent.
+export function authorize(intent: Intent, quote: Quote, signer: Signer, signedAt: number): Authorization {
+  if (quote.intentId !== intent.id) {
+    throw new Error("pact: quote does not belong to intent");
+  }
+  const preimage = signingPreimage(intentHash(intent), quoteHash(quote), signer.identity(), signedAt);
+  return {
+    intentId: intent.id,
+    quoteId: quote.id,
+    signerIdentity: signer.identity(),
+    signedAt,
+    signature: signer.sign(preimage),
+  };
+}
+
+// verifyAuthorization checks that an authorization was signed for exactly this
+// intent and quote. Binding both hashes into the preimage makes a captured
+// signature useless against any other intent or quote.
+export function verifyAuthorization(auth: Authorization, intent: Intent, quote: Quote, verifier: Verifier): void {
+  if (auth.intentId !== intent.id || auth.quoteId !== quote.id || quote.intentId !== intent.id) {
+    throw new Error("pact: authorization does not match intent and quote");
+  }
+  const preimage = signingPreimage(intentHash(intent), quoteHash(quote), auth.signerIdentity, auth.signedAt);
+  if (!verifier.verify(auth.signerIdentity, preimage, auth.signature)) {
+    throw new BadSignatureError();
+  }
+}
+
+// Ed25519Signer is the reference signer used by the shared test vectors and by
+// hosts whose identity key is an Ed25519 key. Hosts that sign with a
+// smart-account validator supply their own Signer instead.
+export class Ed25519Signer implements Signer {
+  private readonly privateKey: KeyObject;
+  readonly publicKey: Uint8Array;
+
+  private constructor(private readonly id: string, privateKey: KeyObject, publicKey: Uint8Array) {
+    this.privateKey = privateKey;
+    this.publicKey = publicKey;
+  }
+
+  static fromSeed(identity: string, seed: Uint8Array): Ed25519Signer {
+    const { privateKey, publicKey } = ed25519KeyFromSeed(seed);
+    return new Ed25519Signer(identity, privateKey, publicKey);
+  }
+
+  identity(): string {
+    return this.id;
+  }
+
+  sign(preimage: Uint8Array): Uint8Array {
+    return ed25519Sign(this.privateKey, preimage);
+  }
+}
+
+// Ed25519Verifier resolves an identity string to its Ed25519 public key. A real
+// host resolves keys from its own key directory instead of a map.
+export class Ed25519Verifier implements Verifier {
+  constructor(private readonly keys: Map<string, Uint8Array>) {}
+
+  verify(identity: string, preimage: Uint8Array, signature: Uint8Array): boolean {
+    const pub = this.keys.get(identity);
+    if (!pub) return false;
+    return ed25519Verify(pub, preimage, signature);
+  }
+}