@myzonerocks/pact 0.1.0

package/dist/src/bridge.d.ts

@@ -0,0 +1,40 @@
+import { Money } from "./money.js";
+export declare const BRIDGE_USDC = "usdc";
+export interface BridgeQuote {
+    srcAmount: Money;
+    fxRate: string;
+    fee: Money;
+}
+export interface ConvertResult {
+    delivered: Money;
+    receiptRef: string;
+}
+export interface Bridge {
+    id: string;
+    quote(dstTarget: Money, srcCurrency: string, srcExponent: number): Promise<BridgeQuote>;
+    convert(intentId: string, held: Money, dstCurrency: string, dstExponent: number): Promise<ConvertResult>;
+}
+export interface RateSource {
+    rate(from: string, to: string): Promise<string>;
+}
+export interface EscrowVault {
+    hold(intentId: string, amount: Money): Promise<string>;
+    release(intentId: string): Promise<void>;
+}
+export declare class PassThroughBridge implements Bridge {
+    readonly id = "passthrough";
+    quote(dstTarget: Money, srcCurrency: string, srcExponent: number): Promise<BridgeQuote>;
+    convert(_intentId: string, held: Money, dstCurrency: string, dstExponent: number): Promise<ConvertResult>;
+}
+export declare class UsdcBridge implements Bridge {
+    private readonly rates;
+    private readonly vault;
+    private readonly feeBps;
+    readonly id = "usdc";
+    constructor(rates: RateSource, vault: EscrowVault, feeBps: bigint);
+    quote(dstTarget: Money, srcCurrency: string, srcExponent: number): Promise<BridgeQuote>;
+    convert(intentId: string, held: Money, dstCurrency: string, dstExponent: number): Promise<ConvertResult>;
+}
+export declare function applyRate(src: Money, rate: string, dstCurrency: string, dstExponent: number): Money;
+export declare function applyInverseRate(dst: Money, rate: string, srcCurrency: string, srcExponent: number): Money;
+export declare function parseRate(rate: string): [bigint, bigint];

package/dist/src/bridge.js

@@ -0,0 +1,99 @@
+import { Money } from "./money.js";
+import { BRIDGE_PASSTHROUGH } from "./message.js";
+// The USDC bridge identifier. A stable wire value carried in a corridor quote.
+export const BRIDGE_USDC = "usdc";
+// PassThroughBridge is the direct-corridor bridge: it moves value unchanged when
+// the payer and recipient are already in the same currency.
+export class PassThroughBridge {
+    id = BRIDGE_PASSTHROUGH;
+    async quote(dstTarget, srcCurrency, srcExponent) {
+        if (dstTarget.currency !== srcCurrency || dstTarget.exponent !== srcExponent) {
+            throw new Error(`pact: pass-through bridge cannot convert ${srcCurrency} to ${dstTarget.currency}`);
+        }
+        return { srcAmount: dstTarget, fxRate: "1", fee: Money.create(srcCurrency, srcExponent, 0n) };
+    }
+    async convert(_intentId, held, dstCurrency, dstExponent) {
+        if (held.currency !== dstCurrency || held.exponent !== dstExponent) {
+            throw new Error("pact: pass-through bridge cannot convert across currencies");
+        }
+        return { delivered: held, receiptRef: "" };
+    }
+}
+// UsdcBridge converts the payer's currency to the recipient's through a USDC
+// escrow. It applies a quoted rate from the injected RateSource, charges a fee in
+// basis points, and parks the value in the injected EscrowVault between legs.
+export class UsdcBridge {
+    rates;
+    vault;
+    feeBps;
+    id = BRIDGE_USDC;
+    constructor(rates, vault, feeBps) {
+        this.rates = rates;
+        this.vault = vault;
+        this.feeBps = feeBps;
+    }
+    async quote(dstTarget, srcCurrency, srcExponent) {
+        const rate = await this.rates.rate(srcCurrency, dstTarget.currency);
+        // Plan backwards: the source needed to deliver the target is the target at
+        // the inverse rate, rounded up so a rounding remainder never short-changes
+        // the recipient.
+        const src = applyInverseRate(dstTarget, rate, srcCurrency, srcExponent);
+        const feeMinor = (src.value() * this.feeBps) / 10000n;
+        return { srcAmount: src, fxRate: rate, fee: Money.create(srcCurrency, srcExponent, feeMinor) };
+    }
+    async convert(intentId, held, dstCurrency, dstExponent) {
+        const ref = await this.vault.hold(intentId, held);
+        const rate = await this.rates.rate(held.currency, dstCurrency);
+        const delivered = applyRate(held, rate, dstCurrency, dstExponent);
+        await this.vault.release(intentId);
+        return { delivered, receiptRef: ref };
+    }
+}
+// applyRate converts a source amount to a destination currency at a decimal rate.
+// The rate is Y per X given as an integer or a fixed-point decimal; the result is
+// floored to the destination currency's minor unit. Rounding down is deliberate:
+// the recipient is never credited more than the rate permits.
+export function applyRate(src, rate, dstCurrency, dstExponent) {
+    const [num, den] = parseRate(rate);
+    // dstMinor = srcMinor * rate * 10^(dstExponent - srcExponent)
+    let value = src.value() * num;
+    let denom = den;
+    if (dstExponent >= src.exponent) {
+        value = value * pow10(dstExponent - src.exponent);
+    }
+    else {
+        denom = denom * pow10(src.exponent - dstExponent);
+    }
+    return Money.create(dstCurrency, dstExponent, value / denom);
+}
+// applyInverseRate is the planning direction: given a target destination amount
+// and a rate of Y per X, it returns the source amount needed. It rounds up so a
+// rounding remainder is covered by the payer, never taken from the recipient.
+export function applyInverseRate(dst, rate, srcCurrency, srcExponent) {
+    const [num, den] = parseRate(rate);
+    // srcMinor = ceil( dstMinor * den * 10^srcExp / (num * 10^dstExp) )
+    const numerator = dst.value() * den * pow10(srcExponent);
+    const denominator = num * pow10(dst.exponent);
+    let value = numerator / denominator;
+    if (numerator % denominator !== 0n) {
+        value = value + 1n;
+    }
+    return Money.create(srcCurrency, srcExponent, value);
+}
+// parseRate reads a decimal rate like "129.45" into a numerator and denominator,
+// so the conversion stays exact integer arithmetic with no floating point.
+export function parseRate(rate) {
+    const dot = rate.indexOf(".");
+    const whole = dot < 0 ? rate : rate.slice(0, dot);
+    const frac = dot < 0 ? "" : rate.slice(dot + 1);
+    const digits = whole + frac;
+    if (!/^\d+$/.test(digits)) {
+        throw new Error(`pact: ${JSON.stringify(rate)} is not a decimal rate`);
+    }
+    const num = BigInt(digits);
+    const den = frac.length > 0 ? pow10(frac.length) : 1n;
+    return [num, den];
+}
+function pow10(n) {
+    return 10n ** BigInt(n);
+}

package/dist/src/canonical.d.ts

@@ -0,0 +1,14 @@
+import { Money } from "./money.js";
+export declare class CanonicalWriter {
+    private readonly parts;
+    private length;
+    private push;
+    bytes(b: Uint8Array): this;
+    str(s: string): this;
+    u64(n: number | bigint): this;
+    money(m: Money): this;
+    list(xs: readonly string[]): this;
+    stringMap(kv: Readonly<Record<string, string>>): this;
+    preimage(): Uint8Array;
+}
+export declare function hashPreimage(preimage: Uint8Array): Uint8Array;

package/dist/src/canonical.js

@@ -0,0 +1,82 @@
+import { sha256 } from "./crypto.js";
+const encoder = new TextEncoder();
+// CanonicalWriter builds a deterministic, length-delimited byte string. It is the
+// one encoder every signed and hashed preimage is built with, mirrored
+// field-for-field across the SDKs. Protobuf is deliberately not used here: its
+// serialization is not canonical across runtimes, so a signature over protobuf
+// bytes would not verify between implementations.
+export class CanonicalWriter {
+    parts = [];
+    length = 0;
+    push(part) {
+        this.parts.push(part);
+        this.length += part.length;
+    }
+    // bytes writes a 4-byte big-endian length followed by the raw bytes.
+    bytes(b) {
+        const header = new Uint8Array(4);
+        new DataView(header.buffer).setUint32(0, b.length, false);
+        this.push(header);
+        this.push(b);
+        return this;
+    }
+    str(s) {
+        return this.bytes(encoder.encode(s));
+    }
+    u64(n) {
+        const b = new Uint8Array(8);
+        new DataView(b.buffer).setBigUint64(0, BigInt(n), false);
+        this.push(b);
+        return this;
+    }
+    money(m) {
+        this.str(m.minor());
+        this.str(m.currency);
+        this.u64(m.exponent);
+        return this;
+    }
+    list(xs) {
+        this.u64(xs.length);
+        for (const x of xs) {
+            this.str(x);
+        }
+        return this;
+    }
+    // stringMap writes a length then each entry, keys sorted ascending by UTF-8
+    // byte value so the encoding never depends on insertion order. The sort is on
+    // encoded bytes, not on UTF-16 code units, to match the other SDKs exactly.
+    stringMap(kv) {
+        const keys = Object.keys(kv).sort(compareUtf8);
+        this.u64(keys.length);
+        for (const k of keys) {
+            this.str(k);
+            this.str(kv[k]);
+        }
+        return this;
+    }
+    preimage() {
+        const out = new Uint8Array(this.length);
+        let offset = 0;
+        for (const part of this.parts) {
+            out.set(part, offset);
+            offset += part.length;
+        }
+        return out;
+    }
+}
+function compareUtf8(a, b) {
+    const ab = encoder.encode(a);
+    const bb = encoder.encode(b);
+    const n = Math.min(ab.length, bb.length);
+    for (let i = 0; i < n; i++) {
+        const diff = ab[i] - bb[i];
+        if (diff !== 0)
+            return diff;
+    }
+    return ab.length - bb.length;
+}
+// hashPreimage is the SHA-256 of a preimage. Every message hash and receipt is
+// derived through it.
+export function hashPreimage(preimage) {
+    return sha256(preimage);
+}

package/dist/src/client.d.ts

@@ -0,0 +1,84 @@
+import { State } from "./state.js";
+import { Money } from "./money.js";
+import { type Intent, type Quote, type Authorization, type Settlement } from "./message.js";
+import { type Signer, type Verifier } from "./signing.js";
+import { type Bridge } from "./bridge.js";
+import { type PayInLeg, type PayOutLeg } from "./leg.js";
+import type { AdapterEvent } from "./adapter.js";
+import { type Policy } from "./router.js";
+import { type KycProvider, type RiskHook } from "./compliance.js";
+import { type Ledger, type LedgerEvent } from "./ledger.js";
+export type Clock = () => number;
+export type IdGen = () => string;
+export declare function systemClock(): number;
+export declare function randomId(): string;
+export interface ClientConfig {
+    payIn?: PayInLeg[];
+    payOut?: PayOutLeg[];
+    bridges?: Bridge[];
+    ledger?: Ledger;
+    policy?: Policy;
+    verifier: Verifier;
+    kyc?: KycProvider;
+    risk?: RiskHook;
+    clock?: Clock;
+    idGen?: IdGen;
+    skew?: number;
+    escrowRef?: string;
+}
+export interface IntentSpec {
+    senderRef: string;
+    recipientRef: string;
+    amount: Money;
+    memo?: string;
+    expiresAt: number;
+    allowedRails?: string[];
+    metadata?: Record<string, string>;
+}
+export interface Funding {
+    payInAdapterId: string;
+    currency: string;
+    exponent: number;
+}
+export declare class Client {
+    private readonly payIn;
+    private readonly payOut;
+    private readonly bridges;
+    private readonly ledger;
+    private readonly policy;
+    private readonly verifier;
+    private readonly kyc;
+    private readonly risk;
+    private readonly clock;
+    private readonly idGen;
+    private readonly skew;
+    private readonly escrowRef;
+    private readonly subscribers;
+    constructor(cfg: ClientConfig);
+    createIntent(spec: IntentSpec): Intent;
+    quoteOptions(intent: Intent, funding: Funding[]): Promise<Quote[]>;
+    private composeQuote;
+    private pickPayOut;
+    private payOutRail;
+    private pickBridge;
+    select(quotes: Quote[], identity: string): Promise<Quote>;
+    authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization>;
+    initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State>;
+    advance(intentId: string, adapterId: string, event: AdapterEvent): Promise<{
+        settlement: Settlement;
+        state: State;
+    }>;
+    private holdAndDisburse;
+    private settleBridged;
+    private unwind;
+    private recordFailure;
+    private finishAdvance;
+    private finish;
+    expire(intentId: string): void;
+    subscribe(handler: (event: LedgerEvent) => void): void;
+    history(intentId: string): LedgerEvent[];
+    state(intentId: string): State;
+    head(intentId: string): Uint8Array | undefined;
+    private notify;
+}
+export declare function recipientDestination(intent: Intent): string;