@vallum/sdk 0.0.1-prerelease.0 → 0.1.1

package/README.md

@@ -4,10 +4,10 @@ TypeScript client scaffold for applications integrating with an Vallum policy ga
 
 ## Install
 
-For the npm prerelease, install:
+For the npm release, install:
 
 ```sh
-npm install @vallum/sdk@next
+npm install @vallum/sdk
 ```
 
 See the full package selection and configuration guide in the repository:

package/dist/contracts/iotaEscrowSettlement.d.ts

@@ -0,0 +1,92 @@
+import { type EscrowReceipt, type EscrowSettlementRail, type EscrowSettlementReleaseMode, type ReceiptAmount } from "@vallum/receipts";
+export type EscrowSettlementErrorCode = "IDEMPOTENCY_REPLAYED" | "ESCROW_BINDING_MISMATCH" | "ESCROW_SETTLEMENT_NOT_OPEN" | "ESCROW_STORE_CONFLICT";
+export declare class EscrowSettlementError extends Error {
+    readonly code: EscrowSettlementErrorCode;
+    constructor(code: EscrowSettlementErrorCode, message: string);
+}
+export interface IotaEscrowOpenExecutionRequest {
+    readonly receipt: EscrowReceipt;
+    readonly settlementRail: EscrowSettlementRail;
+    readonly releaseMode: EscrowSettlementReleaseMode;
+    readonly invocationId: string;
+    readonly actionId: string;
+    readonly actionContractId: string;
+    readonly actionContractVersion: string;
+    readonly providerPayoutRef: string;
+    readonly platformFeeRef: string;
+    readonly refundDestinationRef: string;
+    readonly providerNetAmount: ReceiptAmount;
+    readonly platformFeeAmount: ReceiptAmount;
+}
+export interface IotaEscrowReleaseExecutionRequest {
+    readonly receipt: EscrowReceipt;
+    readonly verifierId: string;
+    readonly escrowId: string;
+    readonly invocationId: string;
+    readonly releaseProofHash: string;
+    readonly providerExecutionReceiptHash: string;
+    readonly evidenceAttestationHash: string;
+    readonly settlementReceiptHash: string;
+    readonly buyerFacingReceiptHash: string;
+}
+export interface IotaEscrowRefundExecutionRequest {
+    readonly receipt: EscrowReceipt;
+    readonly escrowId: string;
+    readonly invocationId: string;
+    readonly reason: string;
+    readonly settlementReceiptHash: string;
+    readonly buyerFacingReceiptHash: string;
+}
+export interface IotaEscrowOpenExecutionResult {
+    readonly escrowId: string;
+    readonly transactionDigest: string;
+}
+export interface IotaEscrowSettlementExecutionResult {
+    readonly transactionDigest: string;
+}
+export interface IotaEscrowSettlementExecutor {
+    readonly open: (request: IotaEscrowOpenExecutionRequest) => Promise<IotaEscrowOpenExecutionResult>;
+    readonly release: (request: IotaEscrowReleaseExecutionRequest) => Promise<IotaEscrowSettlementExecutionResult>;
+    readonly refund: (request: IotaEscrowRefundExecutionRequest) => Promise<IotaEscrowSettlementExecutionResult>;
+}
+export interface EscrowSettlementStoreRecord {
+    readonly idempotencyKey: string;
+    readonly receiptId: string;
+    readonly agentId: string;
+    readonly ownerId: string;
+    readonly providerId: string;
+    readonly verifierId: string;
+    readonly escrowId: string;
+    readonly invocationId: string;
+    readonly status: "open" | "released" | "refunded";
+}
+export interface EscrowSettlementStore {
+    readonly getByIdempotencyKey: (idempotencyKey: string) => Promise<EscrowSettlementStoreRecord | undefined>;
+    readonly getByEscrowId: (escrowId: string) => Promise<EscrowSettlementStoreRecord | undefined>;
+    /**
+     * Must reject conflicting idempotency-key or escrow-id bindings. A live executor
+     * should back this with a durable conditional write before funds can move.
+     */
+    readonly put: (record: EscrowSettlementStoreRecord) => Promise<void>;
+}
+export interface IotaEscrowSettlementClientOptions {
+    readonly executor: IotaEscrowSettlementExecutor;
+    readonly store?: EscrowSettlementStore;
+    readonly now?: () => Date;
+}
+export type IotaEscrowOpenInput = IotaEscrowOpenExecutionRequest;
+export type IotaEscrowReleaseInput = IotaEscrowReleaseExecutionRequest;
+export type IotaEscrowRefundInput = IotaEscrowRefundExecutionRequest;
+export interface IotaEscrowSettlementClientResult {
+    readonly receipt: EscrowReceipt;
+}
+export interface IotaEscrowOpenResult extends IotaEscrowSettlementClientResult {
+    readonly escrowId: string;
+    readonly transactionDigest: string;
+}
+export declare function createInMemoryEscrowSettlementStore(): EscrowSettlementStore;
+export declare function createIotaEscrowSettlementClient(options: IotaEscrowSettlementClientOptions): {
+    open(input: IotaEscrowOpenInput): Promise<IotaEscrowOpenResult>;
+    release(input: IotaEscrowReleaseInput): Promise<IotaEscrowSettlementClientResult>;
+    refund(input: IotaEscrowRefundInput): Promise<IotaEscrowSettlementClientResult>;
+};

package/dist/contracts/iotaEscrowSettlement.js

@@ -0,0 +1,225 @@
+import { recordEscrowSettlementOpen, recordEscrowSettlementRefund, recordEscrowSettlementRelease, } from "@vallum/receipts";
+export class EscrowSettlementError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "EscrowSettlementError";
+    }
+}
+export function createInMemoryEscrowSettlementStore() {
+    const byIdempotencyKey = new Map();
+    const byEscrowId = new Map();
+    return {
+        async getByIdempotencyKey(idempotencyKey) {
+            return byIdempotencyKey.get(idempotencyKey);
+        },
+        async getByEscrowId(escrowId) {
+            return byEscrowId.get(escrowId);
+        },
+        async put(record) {
+            const existingByIdempotencyKey = byIdempotencyKey.get(record.idempotencyKey);
+            if (existingByIdempotencyKey && !hasSameEscrowStoreBinding(existingByIdempotencyKey, record)) {
+                throw new EscrowSettlementError("ESCROW_STORE_CONFLICT", "Escrow idempotency key is already bound to another settlement.");
+            }
+            const existingByEscrowId = byEscrowId.get(record.escrowId);
+            if (existingByEscrowId && !hasSameEscrowStoreBinding(existingByEscrowId, record)) {
+                throw new EscrowSettlementError("ESCROW_STORE_CONFLICT", "Escrow id is already bound to another receipt.");
+            }
+            byIdempotencyKey.set(record.idempotencyKey, record);
+            byEscrowId.set(record.escrowId, record);
+        },
+    };
+}
+export function createIotaEscrowSettlementClient(options) {
+    const store = options.store ?? createInMemoryEscrowSettlementStore();
+    const now = () => options.now?.() ?? new Date();
+    const openingIdempotencyKeys = new Set();
+    return {
+        async open(input) {
+            const idempotencyKey = input.receipt.idempotencyKey;
+            if (openingIdempotencyKeys.has(idempotencyKey)) {
+                throw new EscrowSettlementError("IDEMPOTENCY_REPLAYED", "Escrow idempotency key has already been used.");
+            }
+            openingIdempotencyKeys.add(idempotencyKey);
+            try {
+                const existing = await store.getByIdempotencyKey(idempotencyKey);
+                if (existing) {
+                    throw new EscrowSettlementError("IDEMPOTENCY_REPLAYED", "Escrow idempotency key has already been used.");
+                }
+                preflightEscrowSettlementOpen(input);
+                const opened = await options.executor.open(input);
+                const receipt = recordEscrowSettlementOpen(input.receipt, {
+                    at: now(),
+                    settlementRail: input.settlementRail,
+                    escrowId: opened.escrowId,
+                    releaseMode: input.releaseMode,
+                    invocationId: input.invocationId,
+                    actionId: input.actionId,
+                    actionContractId: input.actionContractId,
+                    actionContractVersion: input.actionContractVersion,
+                    providerPayoutRef: input.providerPayoutRef,
+                    platformFeeRef: input.platformFeeRef,
+                    refundDestinationRef: input.refundDestinationRef,
+                    providerNetAmount: input.providerNetAmount,
+                    platformFeeAmount: input.platformFeeAmount,
+                    transactionDigest: opened.transactionDigest,
+                });
+                await store.put(toEscrowSettlementStoreRecord({
+                    receipt: input.receipt,
+                    escrowId: opened.escrowId,
+                    invocationId: input.invocationId,
+                    status: "open",
+                }));
+                return {
+                    receipt,
+                    escrowId: opened.escrowId,
+                    transactionDigest: opened.transactionDigest,
+                };
+            }
+            finally {
+                openingIdempotencyKeys.delete(idempotencyKey);
+            }
+        },
+        async release(input) {
+            const record = await requireOpenStoreRecord(store, input.escrowId, input.invocationId);
+            requireStoreReceiptBinding(record, input.receipt);
+            requireReceiptBinding(input.receipt, input.escrowId, input.invocationId);
+            preflightEscrowSettlementRelease(input);
+            const released = await options.executor.release(input);
+            const receipt = recordEscrowSettlementRelease(input.receipt, {
+                at: now(),
+                verifierId: input.verifierId,
+                escrowId: input.escrowId,
+                invocationId: input.invocationId,
+                releaseProofHash: input.releaseProofHash,
+                providerExecutionReceiptHash: input.providerExecutionReceiptHash,
+                evidenceAttestationHash: input.evidenceAttestationHash,
+                settlementReceiptHash: input.settlementReceiptHash,
+                buyerFacingReceiptHash: input.buyerFacingReceiptHash,
+                transactionDigest: released.transactionDigest,
+            });
+            await store.put(toEscrowSettlementStoreRecord({
+                receipt: input.receipt,
+                escrowId: input.escrowId,
+                invocationId: input.invocationId,
+                status: "released",
+            }));
+            return { receipt };
+        },
+        async refund(input) {
+            const record = await requireOpenStoreRecord(store, input.escrowId, input.invocationId);
+            requireStoreReceiptBinding(record, input.receipt);
+            requireReceiptBinding(input.receipt, input.escrowId, input.invocationId);
+            preflightEscrowSettlementRefund(input);
+            const refunded = await options.executor.refund(input);
+            const receipt = recordEscrowSettlementRefund(input.receipt, {
+                at: now(),
+                escrowId: input.escrowId,
+                invocationId: input.invocationId,
+                reason: input.reason,
+                settlementReceiptHash: input.settlementReceiptHash,
+                buyerFacingReceiptHash: input.buyerFacingReceiptHash,
+                transactionDigest: refunded.transactionDigest,
+            });
+            await store.put(toEscrowSettlementStoreRecord({
+                receipt: input.receipt,
+                escrowId: input.escrowId,
+                invocationId: input.invocationId,
+                status: "refunded",
+            }));
+            return { receipt };
+        },
+    };
+}
+function hasSameEscrowStoreBinding(left, right) {
+    return left.idempotencyKey === right.idempotencyKey
+        && left.receiptId === right.receiptId
+        && left.agentId === right.agentId
+        && left.ownerId === right.ownerId
+        && left.providerId === right.providerId
+        && left.verifierId === right.verifierId
+        && left.escrowId === right.escrowId
+        && left.invocationId === right.invocationId;
+}
+function toEscrowSettlementStoreRecord(input) {
+    return {
+        idempotencyKey: input.receipt.idempotencyKey,
+        receiptId: input.receipt.receiptId,
+        agentId: input.receipt.agentId,
+        ownerId: input.receipt.ownerId,
+        providerId: input.receipt.escrow.providerId,
+        verifierId: input.receipt.escrow.verifierId,
+        escrowId: input.escrowId,
+        invocationId: input.invocationId,
+        status: input.status,
+    };
+}
+function preflightEscrowSettlementOpen(input) {
+    recordEscrowSettlementOpen(input.receipt, {
+        at: new Date(0),
+        settlementRail: input.settlementRail,
+        escrowId: "preflight-escrow",
+        releaseMode: input.releaseMode,
+        invocationId: input.invocationId,
+        actionId: input.actionId,
+        actionContractId: input.actionContractId,
+        actionContractVersion: input.actionContractVersion,
+        providerPayoutRef: input.providerPayoutRef,
+        platformFeeRef: input.platformFeeRef,
+        refundDestinationRef: input.refundDestinationRef,
+        providerNetAmount: input.providerNetAmount,
+        platformFeeAmount: input.platformFeeAmount,
+        transactionDigest: "preflight-digest",
+    });
+}
+function preflightEscrowSettlementRelease(input) {
+    recordEscrowSettlementRelease(input.receipt, {
+        at: new Date(0),
+        verifierId: input.verifierId,
+        escrowId: input.escrowId,
+        invocationId: input.invocationId,
+        releaseProofHash: input.releaseProofHash,
+        providerExecutionReceiptHash: input.providerExecutionReceiptHash,
+        evidenceAttestationHash: input.evidenceAttestationHash,
+        settlementReceiptHash: input.settlementReceiptHash,
+        buyerFacingReceiptHash: input.buyerFacingReceiptHash,
+        transactionDigest: "preflight-digest",
+    });
+}
+function preflightEscrowSettlementRefund(input) {
+    recordEscrowSettlementRefund(input.receipt, {
+        at: new Date(0),
+        escrowId: input.escrowId,
+        invocationId: input.invocationId,
+        reason: input.reason,
+        settlementReceiptHash: input.settlementReceiptHash,
+        buyerFacingReceiptHash: input.buyerFacingReceiptHash,
+        transactionDigest: "preflight-digest",
+    });
+}
+async function requireOpenStoreRecord(store, escrowId, invocationId) {
+    const record = await store.getByEscrowId(escrowId);
+    if (!record || record.status !== "open") {
+        throw new EscrowSettlementError("ESCROW_SETTLEMENT_NOT_OPEN", "Escrow settlement is not open.");
+    }
+    if (record.invocationId !== invocationId) {
+        throw new EscrowSettlementError("ESCROW_BINDING_MISMATCH", "Escrow invocation binding does not match.");
+    }
+    return record;
+}
+function requireStoreReceiptBinding(record, receipt) {
+    if (record.idempotencyKey !== receipt.idempotencyKey ||
+        record.receiptId !== receipt.receiptId ||
+        record.agentId !== receipt.agentId ||
+        record.ownerId !== receipt.ownerId ||
+        record.providerId !== receipt.escrow.providerId ||
+        record.verifierId !== receipt.escrow.verifierId) {
+        throw new EscrowSettlementError("ESCROW_BINDING_MISMATCH", "Escrow receipt binding does not match the stored settlement.");
+    }
+}
+function requireReceiptBinding(receipt, escrowId, invocationId) {
+    if (receipt.escrowSettlement?.escrowId !== escrowId || receipt.escrowSettlement.invocationId !== invocationId) {
+        throw new EscrowSettlementError("ESCROW_BINDING_MISMATCH", "Escrow proof binding does not match the receipt.");
+    }
+}

package/dist/contracts/iotaEscrowSettlementExecutor.d.ts

@@ -0,0 +1,83 @@
+import type { IotaClient } from "@iota/iota-sdk/client";
+import { Transaction, type TransactionObjectInput } from "@iota/iota-sdk/transactions";
+import type { ExecuteSponsoredTransactionRequest, ExecuteSponsoredTransactionResponse, ReserveGasRequest, ReserveGasResponse } from "../types.js";
+import type { IotaEscrowOpenExecutionRequest, IotaEscrowRefundExecutionRequest, IotaEscrowReleaseExecutionRequest, IotaEscrowSettlementExecutor } from "./iotaEscrowSettlement.js";
+export type LiveEscrowSettlementExecutorErrorCode = "ESCROW_EXECUTOR_CONFIG_INVALID" | "ESCROW_EXECUTOR_RESERVE_RESPONSE_INVALID" | "ESCROW_EXECUTOR_EXECUTE_RESPONSE_INVALID" | "ESCROW_EXECUTOR_ESCROW_ID_MISSING";
+export declare class LiveEscrowSettlementExecutorError extends Error {
+    readonly code: LiveEscrowSettlementExecutorErrorCode;
+    constructor(code: LiveEscrowSettlementExecutorErrorCode, message: string);
+}
+export interface IotaEscrowSettlementSigner {
+    readonly address: string;
+    readonly signTransaction: (bytes: Uint8Array) => Promise<{
+        readonly signature: string;
+    }> | {
+        readonly signature: string;
+    };
+}
+export interface IotaEscrowSettlementGateway {
+    readonly reserveGas: (request: ReserveGasRequest) => Promise<ReserveGasResponse>;
+    readonly executeSponsoredTransaction: (request: ExecuteSponsoredTransactionRequest) => Promise<ExecuteSponsoredTransactionResponse>;
+}
+export interface IotaEscrowSettlementMoveContract {
+    readonly packageId: string;
+    readonly moduleName?: string;
+    readonly openFunction?: string;
+    readonly releaseFunction?: string;
+    readonly refundFunction?: string;
+    readonly escrowTypeName?: string;
+    /**
+     * Shared escrows can be released or refunded by the verifier/owner signer.
+     * Transfer-to-owner is available for deployments that wrap release/refund in
+     * a different access pattern.
+     */
+    readonly publishEscrowObject?: "share" | "transfer-to-owner" | "none";
+}
+export interface IotaEscrowSettlementParticipants {
+    readonly ownerAddress: string;
+    readonly providerAddress: string;
+    readonly verifierAddress: string;
+}
+export type IotaEscrowSettlementParticipantResolver = (request: IotaEscrowOpenExecutionRequest) => IotaEscrowSettlementParticipants | Promise<IotaEscrowSettlementParticipants>;
+export type IotaEscrowSettlementAmountResolver = (request: IotaEscrowOpenExecutionRequest) => bigint | number | string | Promise<bigint | number | string>;
+export type IotaEscrowSettlementObjectResolver = (request: IotaEscrowReleaseExecutionRequest | IotaEscrowRefundExecutionRequest) => TransactionObjectInput | Promise<TransactionObjectInput>;
+export interface IotaEscrowSettlementExecutionContext {
+    readonly operation: "open" | "release" | "refund";
+    readonly reservation: ReserveGasResponse;
+    readonly execution: ExecuteSponsoredTransactionResponse;
+}
+export type IotaEscrowSettlementEscrowIdExtractor = (context: IotaEscrowSettlementExecutionContext & {
+    readonly request: IotaEscrowOpenExecutionRequest;
+}) => string | undefined;
+export interface IotaEscrowSettlementPolicyTarget {
+    readonly packageId?: string;
+    readonly functionName?: string;
+}
+export type IotaEscrowSettlementPolicyTargetResolver<Request> = (request: Request) => IotaEscrowSettlementPolicyTarget | Promise<IotaEscrowSettlementPolicyTarget>;
+export interface CreateSponsoredIotaEscrowSettlementExecutorOptions {
+    readonly gateway: IotaEscrowSettlementGateway;
+    readonly contract: IotaEscrowSettlementMoveContract;
+    readonly signer: IotaEscrowSettlementSigner;
+    readonly iotaClient?: IotaClient;
+    readonly gasBudget: number;
+    readonly reserveDurationSecs?: number;
+    readonly resolveParticipants: IotaEscrowSettlementParticipantResolver;
+    readonly amountToBaseUnits: IotaEscrowSettlementAmountResolver;
+    readonly resolveEscrowObject?: IotaEscrowSettlementObjectResolver;
+    readonly extractEscrowId?: IotaEscrowSettlementEscrowIdExtractor;
+    readonly policyTargetForOpen?: IotaEscrowSettlementPolicyTargetResolver<IotaEscrowOpenExecutionRequest>;
+    readonly policyTargetForRelease?: IotaEscrowSettlementPolicyTargetResolver<IotaEscrowReleaseExecutionRequest>;
+    readonly policyTargetForRefund?: IotaEscrowSettlementPolicyTargetResolver<IotaEscrowRefundExecutionRequest>;
+    /**
+     * Unit-test escape hatch for deterministic transaction bytes.
+     *
+     * Live executors should pass `iotaClient` and let the IOTA SDK build bytes
+     * from the configured Move call. This hook can bypass that boundary, so it
+     * also requires `allowUnsafeCustomTransactionBuilder: true`.
+     */
+    readonly unsafeBuildTransactionBytesForTesting?: (tx: Transaction, context: {
+        readonly operation: "open" | "release" | "refund";
+    }) => Promise<Uint8Array> | Uint8Array;
+    readonly allowUnsafeCustomTransactionBuilder?: boolean;
+}
+export declare function createSponsoredIotaEscrowSettlementExecutor(options: CreateSponsoredIotaEscrowSettlementExecutorOptions): IotaEscrowSettlementExecutor;

package/dist/contracts/iotaEscrowSettlementExecutor.js

@@ -0,0 +1,287 @@
+import { toBase64 } from "@iota/bcs";
+import { Transaction } from "@iota/iota-sdk/transactions";
+export class LiveEscrowSettlementExecutorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LiveEscrowSettlementExecutorError";
+    }
+}
+const DEFAULT_MODULE = "escrow";
+const DEFAULT_OPEN_FUNCTION = "create";
+const DEFAULT_RELEASE_FUNCTION = "release";
+const DEFAULT_REFUND_FUNCTION = "refund";
+const DEFAULT_ESCROW_TYPE = "Escrow";
+const MAX_U64 = (1n << 64n) - 1n;
+export function createSponsoredIotaEscrowSettlementExecutor(options) {
+    validateExecutorOptions(options);
+    return {
+        async open(request) {
+            const participants = await options.resolveParticipants(request);
+            requireParticipants(participants);
+            const amount = normalizeU64BaseUnits(await options.amountToBaseUnits(request));
+            const tx = new Transaction();
+            const contract = normalizeContract(options.contract);
+            const createdEscrow = tx.moveCall({
+                target: moveTarget(contract.packageId, contract.moduleName, contract.openFunction),
+                arguments: [
+                    tx.pure.address(participants.ownerAddress),
+                    tx.pure.address(participants.providerAddress),
+                    tx.pure.address(participants.verifierAddress),
+                    tx.pure.u64(amount),
+                    tx.pure.vector("u8", utf8Bytes(request.providerNetAmount.asset)),
+                    tx.pure.vector("u8", utf8Bytes(request.receipt.idempotencyKey)),
+                    tx.pure.vector("u8", utf8Bytes(request.receipt.receiptId)),
+                ],
+            });
+            if (contract.publishEscrowObject === "share") {
+                tx.moveCall({
+                    target: "0x2::transfer::share_object",
+                    typeArguments: [escrowType(contract)],
+                    arguments: [createdEscrow],
+                });
+            }
+            else if (contract.publishEscrowObject === "transfer-to-owner") {
+                tx.transferObjects([createdEscrow], tx.pure.address(participants.ownerAddress));
+            }
+            const policyTarget = await resolvePolicyTarget(options.policyTargetForOpen, request, contract.packageId, contract.openFunction);
+            const executed = await executeSponsoredTransaction(options, tx, {
+                operation: "open",
+                policyTarget,
+            });
+            const escrowId = options.extractEscrowId ? options.extractEscrowId({
+                operation: "open",
+                request,
+                reservation: executed.reservation,
+                execution: executed.execution,
+            }) : defaultEscrowIdExtractor({
+                operation: "open",
+                reservation: executed.reservation,
+                execution: executed.execution,
+            }, escrowType(contract));
+            if (!escrowId) {
+                throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_ESCROW_ID_MISSING", "Live escrow open executed but no escrow object id was available in the bounded response.");
+            }
+            return { escrowId, transactionDigest: executed.digest };
+        },
+        async release(request) {
+            const contract = normalizeContract(options.contract);
+            const escrowObject = await resolveEscrowObject(options, request);
+            const tx = new Transaction();
+            tx.moveCall({
+                target: moveTarget(contract.packageId, contract.moduleName, contract.releaseFunction),
+                arguments: [
+                    tx.object(escrowObject),
+                    tx.pure.vector("u8", utf8Bytes(request.releaseProofHash)),
+                ],
+            });
+            const policyTarget = await resolvePolicyTarget(options.policyTargetForRelease, request, contract.packageId, contract.releaseFunction);
+            const executed = await executeSponsoredTransaction(options, tx, {
+                operation: "release",
+                policyTarget,
+            });
+            return { transactionDigest: executed.digest };
+        },
+        async refund(request) {
+            const contract = normalizeContract(options.contract);
+            const escrowObject = await resolveEscrowObject(options, request);
+            const tx = new Transaction();
+            tx.moveCall({
+                target: moveTarget(contract.packageId, contract.moduleName, contract.refundFunction),
+                arguments: [
+                    tx.object(escrowObject),
+                    tx.pure.vector("u8", utf8Bytes(request.reason)),
+                ],
+            });
+            const policyTarget = await resolvePolicyTarget(options.policyTargetForRefund, request, contract.packageId, contract.refundFunction);
+            const executed = await executeSponsoredTransaction(options, tx, {
+                operation: "refund",
+                policyTarget,
+            });
+            return { transactionDigest: executed.digest };
+        },
+    };
+}
+function validateExecutorOptions(options) {
+    if (!options.gateway) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "A sponsorship gateway client is required.");
+    }
+    if (!options.contract?.packageId) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "An escrow Move package id is required.");
+    }
+    if (!Number.isSafeInteger(options.gasBudget) || options.gasBudget <= 0) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "A positive safe gas budget is required.");
+    }
+    if (!options.signer?.address || !options.signer.signTransaction) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "A settlement signer address and signTransaction method are required.");
+    }
+    if (options.unsafeBuildTransactionBytesForTesting && options.allowUnsafeCustomTransactionBuilder !== true) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "Unsafe custom transaction builder requires allowUnsafeCustomTransactionBuilder: true.");
+    }
+    if (!options.iotaClient && !options.unsafeBuildTransactionBytesForTesting) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "An IOTA client is required for live transaction building.");
+    }
+}
+function normalizeContract(contract) {
+    return {
+        packageId: contract.packageId,
+        moduleName: contract.moduleName ?? DEFAULT_MODULE,
+        openFunction: contract.openFunction ?? DEFAULT_OPEN_FUNCTION,
+        releaseFunction: contract.releaseFunction ?? DEFAULT_RELEASE_FUNCTION,
+        refundFunction: contract.refundFunction ?? DEFAULT_REFUND_FUNCTION,
+        escrowTypeName: contract.escrowTypeName ?? DEFAULT_ESCROW_TYPE,
+        publishEscrowObject: contract.publishEscrowObject ?? "share",
+    };
+}
+function requireParticipants(participants) {
+    if (!participants.ownerAddress || !participants.providerAddress || !participants.verifierAddress) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "Escrow participant resolver must return owner, provider, and verifier addresses.");
+    }
+}
+async function executeSponsoredTransaction(options, tx, input) {
+    const reservation = await options.gateway.reserveGas({
+        gasBudget: options.gasBudget,
+        reserveDurationSecs: options.reserveDurationSecs,
+        walletAddress: options.signer.address,
+        packageId: input.policyTarget.packageId,
+        functionName: input.policyTarget.functionName,
+    });
+    const gasCoin = firstGasCoin(reservation);
+    if (!reservation.sponsorAddress || !gasCoin) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_RESERVE_RESPONSE_INVALID", "Reserve response did not include sponsor gas details required for sponsored execution.");
+    }
+    tx.setSender(options.signer.address);
+    tx.setGasOwner(reservation.sponsorAddress);
+    tx.setGasBudget(options.gasBudget);
+    tx.setGasPayment([gasCoin]);
+    const transactionBytes = await buildTransactionBytes(options, tx, input.operation);
+    const { signature } = await options.signer.signTransaction(transactionBytes);
+    const execution = await options.gateway.executeSponsoredTransaction({
+        reservationId: reservation.reservationId,
+        agentRailTransactionId: reservation.agentRailTransactionId,
+        transactionBytes: toBase64(transactionBytes),
+        userSignature: signature,
+    });
+    if (!execution.digest) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_EXECUTE_RESPONSE_INVALID", "Vallum execute response did not include a transaction digest.");
+    }
+    return { reservation, execution, digest: execution.digest };
+}
+async function buildTransactionBytes(options, tx, operation) {
+    if (options.unsafeBuildTransactionBytesForTesting) {
+        return options.unsafeBuildTransactionBytesForTesting(tx, { operation });
+    }
+    if (!options.iotaClient) {
+        throw new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "An IOTA client is required for live transaction building.");
+    }
+    return tx.build({ client: options.iotaClient });
+}
+function normalizeU64BaseUnits(value) {
+    if (typeof value === "bigint") {
+        requireU64Range(value);
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value)) {
+            throw invalidAmountError();
+        }
+        requireU64Range(BigInt(value));
+        return value;
+    }
+    if (!/^(0|[1-9]\d*)$/.test(value)) {
+        throw invalidAmountError();
+    }
+    requireU64Range(BigInt(value));
+    return value;
+}
+function requireU64Range(value) {
+    if (value < 0n || value > MAX_U64) {
+        throw invalidAmountError();
+    }
+}
+function invalidAmountError() {
+    return new LiveEscrowSettlementExecutorError("ESCROW_EXECUTOR_CONFIG_INVALID", "Escrow amount resolver must return a non-negative u64-safe integer base-unit amount.");
+}
+function firstGasCoin(reservation) {
+    const coin = reservation.gasCoins?.[0];
+    if (!isRecord(coin))
+        return undefined;
+    const objectId = stringField(coin, "objectId");
+    const digest = stringField(coin, "digest");
+    const version = coin["version"];
+    if (!objectId || !digest || (typeof version !== "string" && typeof version !== "number"))
+        return undefined;
+    return { objectId, version, digest };
+}
+function defaultEscrowIdExtractor(context, expectedObjectType) {
+    const raw = context.execution.raw;
+    const record = isRecord(raw) ? raw : {};
+    const explicit = stringField(record, "escrowId") ?? stringField(record, "escrow_id");
+    if (explicit)
+        return explicit;
+    const objectChanges = Array.isArray(record["objectChanges"]) ? record["objectChanges"] : [];
+    let firstCreatedObjectId;
+    let sawTypedCreatedObject = false;
+    for (const change of objectChanges) {
+        if (!isRecord(change) || change["type"] !== "created")
+            continue;
+        const objectId = stringField(change, "objectId") ?? stringField(change, "object_id");
+        if (!objectId)
+            continue;
+        if (!firstCreatedObjectId)
+            firstCreatedObjectId = objectId;
+        const objectType = stringField(change, "objectType") ?? stringField(change, "object_type");
+        if (objectType)
+            sawTypedCreatedObject = true;
+        if (objectType === expectedObjectType)
+            return objectId;
+    }
+    if (!sawTypedCreatedObject && firstCreatedObjectId)
+        return firstCreatedObjectId;
+    const effects = isRecord(record["effects"]) ? record["effects"] : {};
+    const created = Array.isArray(effects["created"]) ? effects["created"] : [];
+    for (const createdObject of created) {
+        const objectId = objectIdFromCreatedObject(createdObject);
+        if (objectId)
+            return objectId;
+    }
+    return undefined;
+}
+function objectIdFromCreatedObject(value) {
+    if (!isRecord(value))
+        return undefined;
+    const direct = stringField(value, "objectId") ?? stringField(value, "object_id");
+    if (direct)
+        return direct;
+    const reference = isRecord(value["reference"]) ? value["reference"] : undefined;
+    if (reference)
+        return stringField(reference, "objectId") ?? stringField(reference, "object_id");
+    return undefined;
+}
+async function resolveEscrowObject(options, request) {
+    return options.resolveEscrowObject ? options.resolveEscrowObject(request) : request.escrowId;
+}
+async function resolvePolicyTarget(resolver, request, packageId, functionName) {
+    const target = resolver ? await resolver(request) : {};
+    return {
+        packageId: target.packageId ?? packageId,
+        functionName: target.functionName ?? functionName,
+    };
+}
+function moveTarget(packageId, moduleName, functionName) {
+    return `${packageId}::${moduleName}::${functionName}`;
+}
+function escrowType(contract) {
+    return `${contract.packageId}::${contract.moduleName}::${contract.escrowTypeName}`;
+}
+function utf8Bytes(value) {
+    return Array.from(new TextEncoder().encode(value));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./IotaAgent.js";
 export * from "./client.js";
 export * from "./contracts/dataLicense.js";
+export * from "./contracts/iotaEscrowSettlement.js";
+export * from "./contracts/iotaEscrowSettlementExecutor.js";
 export * from "./contracts/openEscrow.js";
 export * from "./contracts/payPerCall.js";
 export * from "./contracts/reputationReceipt.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "./IotaAgent.js";
 export * from "./client.js";
 export * from "./contracts/dataLicense.js";
+export * from "./contracts/iotaEscrowSettlement.js";
+export * from "./contracts/iotaEscrowSettlementExecutor.js";
 export * from "./contracts/openEscrow.js";
 export * from "./contracts/payPerCall.js";
 export * from "./contracts/reputationReceipt.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vallum/sdk",
-  "version": "0.0.1-prerelease.0",
+  "version": "0.1.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,13 +12,15 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@vallum/manifest": "0.0.1-prerelease.0",
-    "@vallum/registry": "0.0.1-prerelease.0",
-    "@vallum/receipts": "0.0.1-prerelease.0",
-    "@vallum/shared-types": "0.0.1-prerelease.0"
+    "@iota/bcs": "1.6.0",
+    "@iota/iota-sdk": "1.14.0",
+    "@vallum/manifest": "0.1.1",
+    "@vallum/registry": "0.1.1",
+    "@vallum/receipts": "0.1.1",
+    "@vallum/shared-types": "0.1.1"
   },
   "devDependencies": {
-    "@vallum/policy-gateway": "0.0.1-prerelease.0"
+    "@vallum/policy-gateway": "0.1.1"
   },
   "description": "TypeScript SDK scaffold for Vallum sponsorship gateways.",
   "files": [
@@ -36,6 +38,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   }
 }