@arcanetech/privacy-sdk-relay 0.2.0

package/README.md

@@ -0,0 +1,59 @@
+# @arcanetech/privacy-sdk-relay
+
+Chain-agnostic protocol relay runtime for Arcane private payment flows.
+
+## Overview
+
+This package owns admission, lifecycle polling, retry, and consented direct-submit fallback for prepared private operations. Callers supply five required ports; `relayApi` and `relayConfig` are optional and enable Protocol Relay. The runtime never inspects opaque package payloads and has no Stellar, Soroban, or zero-knowledge dependencies.
+
+The ports are:
+
+- `store` — pending-operation persistence (survives reload)
+- `submitDirect` — caller-supplied wallet-signed submission (not serializable; after reload only polling and retry remain)
+- `finalizeLocalState` — apply local record updates after success
+- `drainDeliveries` — deliver output notes after success
+- `persistUserTransaction` — record the user-visible transaction after success
+- `relayConfig` / `relayApi` — optional origin and transport used to admit a request, read lifecycle status, and retry an attempt
+
+## Quick example
+
+```ts
+import {
+  createRelayApi,
+  resolveRelayOrigin,
+  submitAndAwaitPrivateOperation,
+  throwIfRelayUnsuccessful,
+  type ProtocolRelayPorts,
+} from '@arcanetech/privacy-sdk-relay';
+
+const origin = resolveRelayOrigin(relayOriginFromEnv);
+const ports: ProtocolRelayPorts = {
+  store,
+  submitDirect,
+  finalizeLocalState,
+  drainDeliveries,
+  persistUserTransaction,
+  ...(origin
+    ? { relayConfig: { origin }, relayApi: createRelayApi({ origin }) }
+    : {}),
+};
+
+const result = await submitAndAwaitPrivateOperation({ ports, operation });
+const { txId } = throwIfRelayUnsuccessful(result);
+```
+
+Relaying is off until `relayConfig.origin` is set. An unset origin Direct-submits even when the caller marks the operation as `relay`, and the relayer is never contacted.
+
+Substitute `relayApi` (or the optional `fetch` on `createRelayApi`) in tests. Direct submission stays a caller-supplied port because it closes over a prepared operation that cannot be serialized.
+
+## Public API boundaries
+
+- Bind ports in the application; keep chain-specific finalize, delivery, and persist adapters there.
+- Pass the opaque relay package through unchanged. Routing follows the caller-supplied `submissionPath`; this package does not inspect deposit amounts or display kind.
+- This package owns the wire vocabulary: lifecycle statuses (`RELAY_STATUS`), public/HTTP reason codes, and JSON serialization (`serializeRelayPackage` / `deserializeRelayPackage`). Serialization copies package fields only and never inspects proof or public-signal bytes.
+- After a reload, resume with `resumePendingOperations` and `retryFailedRelayAttempt`. Direct fallback requires an in-memory submitter the caller registered before unload.
+
+## Related docs
+
+- [Root README](../../README.md)
+- [Packages](../../docs/overview/packages.mdx)

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+declare function jsonSafeClone(value: unknown): unknown;
+
+declare function resolveRelayOrigin(origin?: string): string | undefined;
+declare function isRelayConfigured(config?: {
+    origin?: string;
+}): boolean;
+
+declare const SUBMISSION_PATH: {
+    readonly direct: "direct";
+    readonly relay: "relay";
+};
+type SubmissionPath = (typeof SUBMISSION_PATH)[keyof typeof SUBMISSION_PATH];
+declare const RELAY_STATUS: {
+    readonly accepted: "accepted";
+    readonly validating: "validating";
+    readonly queued: "queued";
+    readonly submitted: "submitted";
+    readonly reconciling: "reconciling";
+    readonly succeeded: "succeeded";
+    readonly rejected: "rejected";
+    readonly failed: "failed";
+};
+type RelayLifecycleStatus = (typeof RELAY_STATUS)[keyof typeof RELAY_STATUS];
+declare const PENDING_OPERATION_PHASE: {
+    readonly prepared: "prepared";
+    readonly relayAccepted: "relay_accepted";
+    readonly admissionFailed: "admission_failed";
+    readonly succeeded: "succeeded";
+    readonly rejected: "rejected";
+    readonly failed: "failed";
+    readonly settlementTimedOut: "settlement_timed_out";
+};
+type PendingOperationPhase = (typeof PENDING_OPERATION_PHASE)[keyof typeof PENDING_OPERATION_PHASE];
+type RelayPackageJson = {
+    version: number;
+    poolSelector: string;
+    zkConfigNonce: string;
+    proofBytes: string;
+    publicSignals: string;
+    applicationIdHints: string[];
+    ciphertextBytes?: string;
+    outputNoteEphemeralScalars?: string[];
+    escrowAuthorization?: string;
+    keyVersionHints?: Array<number | undefined>;
+};
+type SafeDisplayMetadata = {
+    kind: 'deposit' | 'transfer' | 'withdraw';
+    assetId: string;
+    amountDisplay: number;
+    counterparty: string;
+    senderPrivateAddress: string;
+};
+type DeliveryOutboxEntry = {
+    recipientPrivateAddress: string;
+    commitmentHex: string;
+    coinNote: Record<string, string>;
+    depositScalarHex: string;
+    precommitementHex?: string;
+    assetId: string;
+    amountDisplay: number;
+};
+type SdkFinalizationSnapshot = {
+    consumedRecordIds: string[];
+    outputRecords: DeliveryOutboxEntry[];
+};
+type PendingPrivateOperation = {
+    id: string;
+    walletPublicKey: string;
+    phase: PendingOperationPhase;
+    retryAllowed: boolean;
+    display: SafeDisplayMetadata;
+    snapshot: SdkFinalizationSnapshot;
+    deliveryOutbox: DeliveryOutboxEntry[];
+    relayPackage: RelayPackageJson;
+    finalized: boolean;
+    deliveriesDrained: boolean;
+    transactionPersisted: boolean;
+    escrowSend?: boolean;
+    relayRequestId?: string;
+    relayStatus?: RelayLifecycleStatus;
+    publicReason?: string;
+    transactionHash?: string;
+};
+type RelayRequestAccepted = {
+    relayRequestId: string;
+    status: string;
+    createdAt: string;
+    statusUrl: string;
+};
+type RelayRequestStatus = {
+    relayRequestId: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+    retryAllowed: boolean;
+    attemptNumber?: number;
+    transactionHash?: string;
+    publicReason?: string;
+};
+type RelayApi = {
+    createRequest: (body: RelayPackageJson) => Promise<RelayRequestAccepted>;
+    readStatus: (relayRequestId: string) => Promise<RelayRequestStatus>;
+    retryAttempt: (relayRequestId: string) => Promise<RelayRequestStatus>;
+};
+type PendingPrivateOperationStore = {
+    save: (operation: PendingPrivateOperation) => Promise<void>;
+    list: (walletPublicKey: string) => Promise<PendingPrivateOperation[]>;
+    read: (input: {
+        walletPublicKey: string;
+        operationId: string;
+    }) => Promise<PendingPrivateOperation | undefined>;
+};
+type RelayRuntimeConfig = {
+    origin: string;
+};
+type ProtocolRelayPorts = {
+    relayApi?: RelayApi;
+    relayConfig?: RelayRuntimeConfig;
+    store: PendingPrivateOperationStore;
+    submitDirect: (operation: PendingPrivateOperation) => Promise<{
+        txId: string;
+    }>;
+    finalizeLocalState: (input: {
+        operation: PendingPrivateOperation;
+        txId: string;
+    }) => Promise<void>;
+    drainDeliveries: (input: {
+        operation: PendingPrivateOperation;
+        txId: string;
+    }) => Promise<string | undefined>;
+    persistUserTransaction: (input: {
+        operation: PendingPrivateOperation;
+        txId: string;
+    }) => void;
+};
+type NewPrivateOperation = {
+    id: string;
+    walletPublicKey: string;
+    submissionPath: SubmissionPath;
+    display: SafeDisplayMetadata;
+    snapshot: SdkFinalizationSnapshot;
+    deliveryOutbox: DeliveryOutboxEntry[];
+    relayPackage: RelayPackageJson;
+    escrowSend?: boolean;
+};
+type SubmitPrivateOperationResult = {
+    outcome: PendingOperationPhase;
+    operation: PendingPrivateOperation;
+    txId?: string;
+    coinDeliveryWarning?: string;
+    fallbackAllowed: boolean;
+    retryAllowed: boolean;
+};
+type CreateRelayApiInput = {
+    origin: string;
+    fetch?: typeof globalThis.fetch;
+};
+
+declare function createRelayApi(input: CreateRelayApiInput): RelayApi;
+
+declare class RelayApiError extends Error {
+    readonly reason: string;
+    readonly httpStatus: number;
+    constructor(input: {
+        reason: string;
+        httpStatus: number;
+    });
+}
+declare function isInfrastructureRelayFailure(error: RelayApiError): boolean;
+declare function isRelayApiError(error: unknown): error is RelayApiError;
+
+declare function canOfferDirectSubmission(operation: PendingPrivateOperation): boolean;
+declare function canRetryRelayAttempt(operation: PendingPrivateOperation): boolean;
+
+declare function isUnfinalizedRelayOperation(operation: {
+    relayRequestId?: string;
+    finalized: boolean;
+}): boolean;
+
+declare function submitPreparedPrivateOperation(input: {
+    ports: ProtocolRelayPorts;
+    operation: NewPrivateOperation;
+}): Promise<SubmitPrivateOperationResult>;
+
+declare function pollPendingOperation(input: {
+    ports: ProtocolRelayPorts;
+    walletPublicKey: string;
+    operationId: string;
+}): Promise<SubmitPrivateOperationResult>;
+declare function isTerminalRelayStatus(status: string | undefined): boolean;
+
+declare function retryFailedRelayAttempt(input: {
+    ports: ProtocolRelayPorts;
+    walletPublicKey: string;
+    operationId: string;
+}): Promise<SubmitPrivateOperationResult>;
+declare function resumePendingOperations(input: {
+    ports: ProtocolRelayPorts;
+    walletPublicKey: string;
+}): Promise<SubmitPrivateOperationResult[]>;
+
+declare function submitDirectFallback(input: {
+    ports: ProtocolRelayPorts;
+    walletPublicKey: string;
+    operationId: string;
+    consent: boolean;
+}): Promise<SubmitPrivateOperationResult>;
+
+declare const DEFAULT_SETTLEMENT_POLL_INTERVAL_MS = 2000;
+declare const DEFAULT_SETTLEMENT_MAX_ATTEMPTS = 15;
+declare function awaitRelaySettlement(input: {
+    ports: ProtocolRelayPorts;
+    walletPublicKey: string;
+    operationId: string;
+    pollIntervalMs?: number;
+    maxAttempts?: number;
+    backoffMultiplier?: number;
+    maxPollIntervalMs?: number;
+    delay?: (ms: number) => Promise<void>;
+}): Promise<SubmitPrivateOperationResult>;
+declare function submitAndAwaitPrivateOperation(input: {
+    ports: ProtocolRelayPorts;
+    operation: NewPrivateOperation;
+    pollIntervalMs?: number;
+    maxAttempts?: number;
+}): Promise<SubmitPrivateOperationResult>;
+
+declare class ProtocolRelayClientError extends Error {
+    readonly outcome: SubmitPrivateOperationResult['outcome'];
+    readonly fallbackAllowed: boolean;
+    readonly retryAllowed: boolean;
+    readonly operationId: string;
+    readonly publicReason?: string;
+    constructor(result: SubmitPrivateOperationResult);
+}
+declare function throwIfRelayUnsuccessful(result: SubmitPrivateOperationResult): {
+    txId: string;
+    coinDeliveryWarning?: string;
+};
+
+declare const RELAY_PACKAGE_VERSION_V1 = 1;
+type RelayPackageSerializable = {
+    version: number;
+    poolSelector: string;
+    zkConfigNonce: {
+        toString(): string;
+    } | string | number;
+    proofBytes: string;
+    publicSignals: string;
+    applicationIdHints: string[];
+    ciphertextBytes?: string;
+    outputNoteEphemeralScalars?: string[];
+    escrowAuthorization?: string;
+    keyVersionHints?: Array<number | undefined | null>;
+};
+declare function serializeRelayPackage(source: RelayPackageSerializable): RelayPackageJson;
+declare function deserializeRelayPackage(payload: unknown): RelayPackageJson | undefined;
+
+declare const RELAY_PUBLIC_REASON: {
+    readonly invalidPackage: "invalid_package";
+    readonly unsupportedSignalShape: "unsupported_signal_shape";
+    readonly positivePublicDeposit: "positive_public_deposit";
+    readonly zkConfigMissing: "zk_config_missing";
+    readonly zkConfigDeprecated: "zk_config_deprecated";
+    readonly zkConfigIncompatible: "zk_config_incompatible";
+    readonly invalidProof: "invalid_proof";
+    readonly kytRejected: "kyt_rejected";
+    readonly kytAuthorizationMismatch: "kyt_authorization_mismatch";
+    readonly escrowRelayUnconfigured: "escrow_relay_unconfigured";
+    readonly escrowAuthorizationMismatch: "escrow_authorization_mismatch";
+    readonly nullifiersSpent: "nullifiers_spent";
+    readonly simulationFailed: "simulation_failed";
+    readonly resourceFeeExceeded: "resource_fee_exceeded";
+    readonly resourceLimitExceeded: "resource_limit_exceeded";
+    readonly sendFailed: "send_failed";
+    readonly transactionFailed: "transaction_failed";
+    readonly infrastructureFailed: "infrastructure_failed";
+};
+type RelayPublicReason = (typeof RELAY_PUBLIC_REASON)[keyof typeof RELAY_PUBLIC_REASON];
+declare const RELAY_HTTP_REASON: {
+    readonly payloadTooLarge: "payload_too_large";
+    readonly rateLimited: "rate_limited";
+    readonly unsupportedPool: "unsupported_pool";
+    readonly queueAtCapacity: "queue_at_capacity";
+    readonly lowBalance: "low_balance";
+    readonly conflictingPayload: "conflicting_payload";
+    readonly retryNotAllowed: "retry_not_allowed";
+    readonly notFound: "not_found";
+    readonly relayerUnavailable: "relayer_unavailable";
+    readonly invalidPackage: "invalid_package";
+    readonly unsupportedSignalShape: "unsupported_signal_shape";
+};
+type RelayHttpReason = (typeof RELAY_HTTP_REASON)[keyof typeof RELAY_HTTP_REASON];
+declare function isRetryableFailureReason(reason: string | null | undefined): boolean;
+declare function isRejectionReason(reason: string): boolean;
+
+export { type CreateRelayApiInput, DEFAULT_SETTLEMENT_MAX_ATTEMPTS, DEFAULT_SETTLEMENT_POLL_INTERVAL_MS, type DeliveryOutboxEntry, type NewPrivateOperation, PENDING_OPERATION_PHASE, type PendingOperationPhase, type PendingPrivateOperation, type PendingPrivateOperationStore, ProtocolRelayClientError, type ProtocolRelayPorts, RELAY_HTTP_REASON, RELAY_PACKAGE_VERSION_V1, RELAY_PUBLIC_REASON, RELAY_STATUS, type RelayApi, RelayApiError, type RelayHttpReason, type RelayLifecycleStatus, type RelayPackageJson, type RelayPackageSerializable, type RelayPublicReason, type RelayRequestAccepted, type RelayRequestStatus, type RelayRuntimeConfig, SUBMISSION_PATH, type SafeDisplayMetadata, type SdkFinalizationSnapshot, type SubmissionPath, type SubmitPrivateOperationResult, awaitRelaySettlement, canOfferDirectSubmission, canRetryRelayAttempt, createRelayApi, deserializeRelayPackage, isInfrastructureRelayFailure, isRejectionReason, isRelayApiError, isRelayConfigured, isRetryableFailureReason, isTerminalRelayStatus, isUnfinalizedRelayOperation, jsonSafeClone, pollPendingOperation, resolveRelayOrigin, resumePendingOperations, retryFailedRelayAttempt, serializeRelayPackage, submitAndAwaitPrivateOperation, submitDirectFallback, submitPreparedPrivateOperation, throwIfRelayUnsuccessful };