@arcenpay/node 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,1083 @@
+import { X402VerifiedPaymentContext, ArcenCompanyKeys, ArcenUserKeys, IdentifyResult, ConsumeEntitlementResult, FlagResult, EntitlementResult, ArcenCompany, EmbedAccessTokenResponse, UsageProof, PublicInputs, BillingSettlement, PlanTier } from '@arcenpay/sdk';
+export { ArcenCompany, ArcenCompanyKeys, ArcenUser, ArcenUserKeys, ConsumeEntitlementResult, EntitlementResult, FlagResult, IdentifyResult } from '@arcenpay/sdk';
+import { Request, Response, NextFunction } from 'express';
+export { TablelandConfig, TablelandService } from './tableland.mjs';
+
+declare global {
+  namespace Express {
+    interface Request {
+      meapPayment?: X402VerifiedPaymentContext;
+    }
+  }
+}
+
+/**
+ * ArcenClient — Node.js SDK for the ArcenPay Protocol.
+ *
+ * Usage pattern (Schematic-style):
+ *  1. Call identify() once per session → stores session token
+ *  2. Call checkFlag() / checkEntitlement() / track() with no keys
+ */
+
+interface ArcenClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+interface TrackEventInput {
+    name: string;
+    company?: ArcenCompanyKeys;
+    user?: ArcenUserKeys;
+    traits?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+interface IdentifyInput {
+    company?: ArcenCompanyKeys & {
+        name?: string;
+        traits?: Record<string, unknown>;
+    };
+    user?: ArcenUserKeys & {
+        name?: string;
+        email?: string;
+    };
+    expiresIn?: number;
+}
+interface ActivateSubscriptionInput {
+    planId: string | number | bigint;
+    paymentAccount: string;
+    company: ArcenCompanyKeys & {
+        name?: string;
+        traits?: Record<string, unknown>;
+    };
+    subscriberEmail?: string;
+}
+interface ActivateSubscriptionResult {
+    tokenId: string;
+    txHash: string;
+    companyId: string;
+    planId: string;
+    paymentAccount: string;
+}
+interface ConsumeEntitlementInput {
+    featureKey: string;
+    company?: ArcenCompanyKeys;
+    user?: ArcenUserKeys;
+    traits?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+declare class ArcenClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private session;
+    constructor(config: ArcenClientConfig);
+    private buildAuthHeader;
+    private request;
+    identify(input: IdentifyInput): Promise<IdentifyResult>;
+    track(event: string | TrackEventInput): Promise<void>;
+    consumeEntitlement(input: string | ConsumeEntitlementInput): Promise<ConsumeEntitlementResult>;
+    checkFlag(key: string, companyKeys?: ArcenCompanyKeys, userKeys?: ArcenUserKeys): Promise<FlagResult>;
+    checkEntitlement(key: string, companyKeys?: ArcenCompanyKeys, userKeys?: ArcenUserKeys): Promise<EntitlementResult>;
+    checkFlags(featureKeys: string[], companyKeys?: ArcenCompanyKeys, userKeys?: ArcenUserKeys): Promise<Record<string, FlagResult>>;
+    listCompanies(options?: {
+        limit?: number;
+        search?: string;
+        cursor?: string;
+    }): Promise<{
+        data: ArcenCompany[];
+        count: number;
+        nextCursor?: string;
+    }>;
+    getCompany(id: string): Promise<{
+        data: ArcenCompany & {
+            entitlements: unknown[];
+        };
+    }>;
+    createCompany(data: {
+        name: string;
+        wallet?: string;
+        email?: string;
+        id?: string;
+        traits?: Record<string, unknown>;
+    }): Promise<{
+        data: ArcenCompany;
+    }>;
+    updateCompany(id: string, data: {
+        name?: string;
+        traits?: Record<string, unknown>;
+        activePlanId?: string | null;
+    }): Promise<{
+        data: ArcenCompany;
+    }>;
+    setCompanyOverride(companyId: string, featureKey: string, value: boolean, reason?: string): Promise<void>;
+    activateSubscription(input: ActivateSubscriptionInput): Promise<ActivateSubscriptionResult>;
+    /** @deprecated Use identify() instead */
+    createAccessToken(companyKeys?: ArcenCompanyKeys, userKeys?: ArcenUserKeys, expiresIn?: number): Promise<EmbedAccessTokenResponse>;
+}
+declare class ArcenApiError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+/**
+ * NonceStore — Interface for x402 nonce deduplication.
+ *
+ * Implementations must provide atomic check-and-set semantics:
+ * if `markUsed` returns true, the nonce was not previously seen
+ * and is now marked as used. If it returns false, the nonce is
+ * a replay and must be rejected.
+ */
+interface NonceStore {
+    /**
+     * Atomically check if nonce was used and mark it used.
+     * @returns true if nonce was fresh (now marked), false if already seen (replay)
+     */
+    markUsed(key: string, ttlMs: number): Promise<boolean>;
+    /** Check if nonce has been used. */
+    has(key: string): Promise<boolean>;
+    /** Stop background processes (timers etc.) */
+    stop(): void;
+}
+declare class InMemoryNonceStore implements NonceStore {
+    private readonly seen;
+    private readonly cleanupTimer;
+    constructor(cleanupIntervalMs?: number);
+    markUsed(key: string, ttlMs: number): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    stop(): void;
+}
+interface RedisLike {
+    set(key: string, value: string, exMode: "EX", exValue: number, nxMode: "NX"): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    quit(): Promise<string>;
+}
+declare class RedisNonceStore implements NonceStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisLike, prefix?: string);
+    markUsed(key: string, ttlMs: number): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    stop(): void;
+}
+
+type X402SettlePaymentInput = {
+    signer: `0x${string}`;
+    amount: bigint;
+    sessionId: string;
+    planId: string;
+    paymentHeader: string;
+    payload: Record<string, unknown>;
+    request: Request;
+};
+type X402SettlePaymentResult = {
+    settledAmount: bigint | string | number;
+    settlementTxHash?: string | null;
+};
+interface X402MiddlewareOptions {
+    /** Plan ID for pricing reference */
+    planId: string;
+    /** Price per API call in USDC (human-readable, e.g., "0.001") */
+    ratePerCall: string;
+    /** Network identifier (e.g., "base-mainnet") */
+    network?: string;
+    /** Chain ID for contract reads */
+    chainId?: number;
+    /** RPC URL for on-chain validation */
+    rpcUrl?: string;
+    /** Payment facilitator contract address */
+    payTo?: string;
+    /** Optional settlement hook. Called after payment verification succeeds. */
+    settlePayment?: (input: X402SettlePaymentInput) => Promise<X402SettlePaymentResult>;
+    /**
+     * If true, allow requests when balance check RPC/contract read fails.
+     * Default false for production-safe fail-closed behavior.
+     */
+    failOpenOnBalanceCheck?: boolean;
+    /**
+     * Maximum age of payment timestamp in milliseconds.
+     * Payments older than this window are rejected.
+     * Default: 300_000 (5 minutes).
+     */
+    maxPaymentAgeMs?: number;
+    /**
+     * TTL for nonce deduplication entries in milliseconds.
+     * Set to at least 2x maxPaymentAgeMs.
+     * Default: 600_000 (10 minutes).
+     */
+    nonceTtlMs?: number;
+    /**
+     * Pluggable nonce store for durable anti-replay protection.
+     * Defaults to InMemoryNonceStore if not provided.
+     * Use RedisNonceStore for multi-instance production deployments.
+     */
+    nonceStore?: NonceStore;
+}
+/**
+ * x402 Express Middleware — Production-grade payment validation
+ *
+ * Validation algorithm (PRD §7.1.1):
+ * 1. Parse X-PAYMENT header (base64 JSON)
+ * 2. Verify EIP-712 typed data signature → recover signer
+ * 3. Verify signer matches payment.from
+ * 4. Check SessionVault.getAgentBalance(signer) >= maxAmountRequired
+ * 5. Return 402 on failure, attach req.meapPayment on success
+ */
+declare function x402Middleware(options: X402MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+interface UsageLogEntry {
+    sessionId: string;
+    callData: {
+        endpoint: string;
+        method: string;
+        timestamp: number;
+        responseSize?: number;
+    };
+    signature: string;
+}
+interface UsageAggregation {
+    sessionId: string;
+    callCount: number;
+    windowStart: number;
+    windowEnd: number;
+    logs: UsageLogEntry[];
+}
+type ProofMode = "strict" | "dev";
+declare const UsageProofErrorCodes: {
+    readonly TOOLING_UNAVAILABLE: "TOOLING_UNAVAILABLE";
+    readonly ARTIFACTS_MISSING: "ARTIFACTS_MISSING";
+    readonly ARTIFACT_VERSION_MISMATCH: "ARTIFACT_VERSION_MISMATCH";
+    readonly INVALID_VERIFICATION_KEY: "INVALID_VERIFICATION_KEY";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PROOF_GENERATION_FAILED: "PROOF_GENERATION_FAILED";
+    readonly PROOF_SIGNAL_MISMATCH: "PROOF_SIGNAL_MISMATCH";
+};
+type UsageProofErrorCode = (typeof UsageProofErrorCodes)[keyof typeof UsageProofErrorCodes];
+declare class UsageProofError extends Error {
+    readonly code: UsageProofErrorCode;
+    readonly cause?: unknown;
+    constructor(code: UsageProofErrorCode, message: string, cause?: unknown);
+}
+interface UsageServiceConfig {
+    signerPrivateKey?: string;
+    chainId?: number;
+    rpcUrl?: string;
+    proofMode?: ProofMode;
+    circuitsRootDir?: string;
+    circuitBuildDir?: string;
+    circuitWasmPath?: string;
+    zkeyPath?: string;
+    verificationKeyPath?: string;
+    proveScriptPath?: string;
+    artifactVersion?: string;
+    artifactManifestPath?: string;
+}
+declare class UsageService {
+    private logs;
+    private readonly config;
+    private readonly signerAccount;
+    private readonly publicClient;
+    private readonly walletClient;
+    private runtimeValidated;
+    constructor(config?: UsageServiceConfig);
+    getProofMode(): ProofMode;
+    getProofRuntimeConfig(): {
+        proofMode: ProofMode;
+        proveScriptPath: string;
+        circuitWasmPath: string;
+        zkeyPath: string;
+        verificationKeyPath: string;
+        artifactVersion: string;
+        artifactManifestPath: string;
+    };
+    assertProofRuntimeReady(): void;
+    logUsage(sessionId: string, callData: UsageLogEntry["callData"]): Promise<void>;
+    getUsageCount(sessionId: string): number;
+    getAllSessions(): string[];
+    aggregateUsage(sessionId: string, windowEnd: number): UsageAggregation;
+    generateProof(sessionId: string, windowEnd: number): Promise<{
+        proof: UsageProof;
+        publicInputs: PublicInputs;
+    }>;
+    submitProof(proof: UsageProof, publicInputs: PublicInputs): Promise<BillingSettlement>;
+    clearLogs(sessionId: string, windowEnd: number): void;
+    private resolveCircuitsRoot;
+    private assertProofTooling;
+    private assertProofArtifacts;
+    private assertArtifactVersion;
+    private assertVerificationKey;
+    private wrapProofError;
+    private loadCircuitProver;
+    private assertPublicSignals;
+    private hashUsageLog;
+    private normalizeBytes32;
+    private addressToBytes32;
+    private fieldToBytes32;
+    private toFieldElement;
+}
+
+type SettlementCallback = (settlement: BillingSettlement) => void;
+/**
+ * SettlementService — Monitors on-chain BillingSettled events
+ * and provides session vault balance queries via viem
+ */
+declare class SettlementService {
+    private rpcUrl;
+    private chainId;
+    private zkVerifierAddress;
+    private sessionVaultAddress;
+    private watchers;
+    private pollInterval;
+    private lastBlock;
+    private publicClient;
+    constructor(config: {
+        rpcUrl: string;
+        chainId?: number;
+        zkVerifierAddress?: string;
+        sessionVaultAddress?: string;
+    });
+    /**
+     * Queries the SessionVault for remaining balance
+     */
+    getSessionBalance(agentAddress: string): Promise<bigint>;
+    /**
+     * Gets details for a specific session
+     */
+    getSessionDetails(sessionId: string): Promise<any>;
+    /**
+     * Subscribes to on-chain BillingSettled events
+     */
+    watchSettlements(callback: SettlementCallback, intervalMs?: number): () => void;
+    /**
+     * Initialize the starting block number for event polling
+     */
+    private initBlockNumber;
+    /**
+     * Polls for new BillingSettled events from ZKUsageVerifier
+     */
+    private pollSettlements;
+    /**
+     * Stops all settlement watchers
+     */
+    stop(): void;
+}
+
+interface SettlementWriterConfig {
+    rpcUrl: string;
+    privateKey: `0x${string}`;
+    chainId?: number;
+    sessionVaultAddress?: `0x${string}`;
+    feeCollectorAddress?: `0x${string}`;
+    providerAddress?: `0x${string}`;
+    waitForReceipt?: boolean;
+}
+interface SettleForSignerInput {
+    signer: `0x${string}`;
+    amount: bigint;
+    sessionIdHint: string;
+    providerAddress?: `0x${string}`;
+}
+interface SettlementWriteResult {
+    transactionHash: `0x${string}`;
+    settledAmount: bigint;
+    sessionId: `0x${string}`;
+    providerAddress: `0x${string}`;
+}
+/**
+ * SettlementWriterService
+ *
+ * Writes `SessionVault.settle(sessionId, amount, provider)` transactions
+ * using a facilitator signer configured in runtime environment.
+ */
+declare class SettlementWriterService {
+    private readonly chainId;
+    private readonly sessionVaultAddress;
+    private readonly feeCollectorAddress;
+    private readonly providerAddress;
+    private readonly signerAddress;
+    private readonly waitForReceipt;
+    private readonly publicClient;
+    private readonly walletClient;
+    constructor(config: SettlementWriterConfig);
+    getSignerAddress(): `0x${string}`;
+    getSessionVaultAddress(): `0x${string}`;
+    isSignerAuthorized(address?: `0x${string}`): Promise<boolean>;
+    private getSession;
+    private resolveSessionId;
+    settleForSigner(input: SettleForSignerInput): Promise<SettlementWriteResult>;
+}
+
+type SubscriptionEventType = 'minted' | 'renewed' | 'cancelled' | 'plan_changed' | 'billing_executed';
+interface SubscriptionEventData {
+    type: SubscriptionEventType;
+    tokenId: bigint;
+    subscriber?: string;
+    planId?: bigint;
+    previousPlanId?: bigint;
+    expiration?: bigint;
+    amountPaid?: bigint;
+    account?: string;
+    merchant?: string;
+    billingReason?: bigint;
+    merchantAmount?: bigint;
+    protocolFee?: bigint;
+    transactionHash: string;
+    blockNumber: bigint;
+    timestamp: number;
+}
+type EventCallback = (event: SubscriptionEventData) => void | Promise<void>;
+/**
+ * EventListenerService — Persistent event watchers for the SubscriptionRegistry.
+ *
+ * Watches for:
+ *  - SubscriptionMinted(subscriber, tokenId, planId, expiration)
+ *  - SubscriptionRenewed(tokenId, newExpiration, amountPaid)
+ *  - SubscriptionCancelled(tokenId)
+ *  - SubscriptionPlanChanged(tokenId, previousPlanId, newPlanId, expiration)
+ *
+ * PRD §9.1 — On-Chain Event Listeners
+ */
+declare class EventListenerService {
+    private publicClient;
+    private registryAddress;
+    private autopayModuleAddress;
+    private callbacks;
+    private pollInterval;
+    private lastBlock;
+    constructor(config: {
+        rpcUrl: string;
+        chainId?: number;
+        registryAddress?: string;
+    });
+    /**
+     * Register a callback for a specific event type (or '*' for all events)
+     */
+    on(eventType: SubscriptionEventType | '*', callback: EventCallback): () => void;
+    /**
+     * Start polling for events at the given interval
+     */
+    start(intervalMs?: number): Promise<void>;
+    /**
+     * Stop polling
+     */
+    stop(): void;
+    /**
+     * Poll for new events since lastBlock
+     */
+    private poll;
+    /**
+     * Dispatch event to registered callbacks
+     */
+    private emit;
+}
+
+interface WebhookConfig {
+    /** Provider-configured webhook endpoint URL */
+    url: string;
+    /** HMAC-SHA256 signing secret */
+    secret: string;
+    /** Max retries (default: 5) */
+    maxRetries?: number;
+    /** Retry delays in ms (exponential backoff) */
+    retryDelays?: number[];
+    /** Optional callback invoked on every delivery attempt (success or failure). */
+    onDelivery?: (entry: WebhookDeliveryLog, payload: WebhookPayload) => Promise<void> | void;
+}
+interface WebhookPayload {
+    event: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+interface WebhookDeliveryLog {
+    id: string;
+    event: string;
+    url: string;
+    statusCode: number | null;
+    attemptNumber: number;
+    deliveredAt: number;
+    success: boolean;
+    error?: string;
+}
+/**
+ * WebhookService — Delivers HMAC-signed webhook payloads
+ * to provider-configured endpoints with exponential backoff retry.
+ *
+ * Payload format:
+ *   { event: 'subscription.renewed', timestamp, data: { tokenId, address, planId, amount, txHash } }
+ *
+ * Signing:
+ *   HMAC-SHA256(JSON.stringify(payload), signingSecret) → X-MEAP-Signature header
+ */
+declare class WebhookService {
+    private config;
+    private deliveryLog;
+    private pendingRetries;
+    constructor(config: WebhookConfig);
+    /**
+     * Deliver a webhook for a subscription event
+     */
+    deliverEvent(event: SubscriptionEventData): Promise<void>;
+    /**
+     * Deliver an arbitrary webhook payload
+     */
+    deliver(payload: WebhookPayload, attempt?: number): Promise<void>;
+    /**
+     * HMAC-SHA256 signature of the payload body
+     */
+    private sign;
+    /**
+     * Schedule a retry with exponential backoff
+     */
+    private scheduleRetry;
+    /**
+     * Log a delivery attempt
+     */
+    private log;
+    private persistDelivery;
+    /**
+     * Get the delivery log for dashboard display
+     */
+    getDeliveryLog(limit?: number): WebhookDeliveryLog[];
+    /**
+     * Verify an incoming webhook signature (for consumers).
+     *
+     * @example
+     * ```ts
+     * import { verifyWebhookSignature } from '@arcenpay/node';
+     *
+     * app.post('/webhooks/meap', (req, res) => {
+     *   const raw = JSON.stringify(req.body);
+     *   const sig = req.headers['x-meap-signature'] as string;
+     *   if (!verifyWebhookSignature(raw, sig, process.env.MEAP_WEBHOOK_SECRET!)) {
+     *     return res.status(401).json({ error: 'Invalid signature' });
+     *   }
+     * });
+     * ```
+     */
+    static verifySignature(body: string, signature: string, secret: string): boolean;
+    /**
+     * Cancel all pending retries and clean up
+     */
+    stop(): void;
+}
+/**
+ * Standalone helper for verifying incoming MEAP webhook signatures.
+ * Equivalent to `WebhookService.verifySignature()` — exported for tree-shaking convenience.
+ *
+ * @param body      - Raw request body string (before any JSON.parse)
+ * @param signature - Value from the `X-MEAP-Signature` request header
+ * @param secret    - Shared HMAC signing secret configured on the provider's webhook endpoint
+ */
+declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;
+
+interface EmailConfig {
+    /** Resend API key */
+    apiKey: string;
+    /** Sender email address (e.g. noreply@arcenpay.io) */
+    fromAddress: string;
+    /** Provider brand name (injected into templates) */
+    brandName?: string;
+}
+interface EmailRecipient {
+    email: string;
+    walletAddress: string;
+    name?: string;
+}
+type EmailTemplate = 'welcome' | 'renewal_receipt' | 'payment_failed' | 'subscription_expiring' | 'access_revoked' | 'low_session_balance';
+/**
+ * EmailService — Transactional email notifications via Resend API.
+ *
+ * Templates: Welcome, Renewal Receipt, Payment Failed,
+ * Subscription Expiring, Access Revoked, Low Session Balance.
+ *
+ * PRD §9.2 — providers configure their Resend API key in Dashboard → Settings.
+ */
+declare class EmailService {
+    private apiKey;
+    private fromAddress;
+    private brandName;
+    constructor(config: EmailConfig);
+    /**
+     * Send an email using a pre-defined template
+     */
+    sendTemplate(template: EmailTemplate, recipient: EmailRecipient, data: Record<string, string>): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+    /**
+     * Build the email payload for a given template
+     */
+    private buildEmail;
+    /**
+     * Wrap template body in a consistent email layout
+     */
+    private wrapInLayout;
+}
+
+interface LitAccessCondition {
+    contractAddress: string;
+    standardContractType: 'ERC721' | 'ERC1155' | 'Custom';
+    chain: string;
+    method: string;
+    parameters: string[];
+    returnValueTest: {
+        comparator: '>' | '<' | '=' | '>=' | '<=';
+        value: string;
+    };
+}
+interface LitConfig {
+    /**
+     * Supported Lit network aliases.
+     * Legacy names are kept for backwards compatibility with older env files.
+     */
+    network: 'manzano' | 'habanero' | 'datil-dev' | 'datil-test' | 'datil';
+    /** SubscriptionRegistry contract address */
+    registryAddress: string;
+    /** Chain name used in ACC conditions (e.g., 'baseSepolia', 'base', 'sepolia') */
+    chain: string;
+}
+type LitAuthInput = {
+    authSig?: unknown;
+    sessionSigs?: unknown;
+};
+declare class LitProtocolService {
+    private config;
+    private litClient;
+    constructor(config: LitConfig);
+    connect(): Promise<void>;
+    buildSubscriptionACC(_walletAddress?: string): LitAccessCondition[];
+    buildTierACC(minimumTier: PlanTier): LitAccessCondition[];
+    encrypt(content: string, accessConditions: LitAccessCondition[]): Promise<{
+        ciphertext: string;
+        dataToEncryptHash: string;
+    }>;
+    decrypt(ciphertext: string, dataToEncryptHash: string, accessConditions: LitAccessCondition[], auth: LitAuthInput): Promise<string>;
+    disconnect(): Promise<void>;
+    private ensureConnected;
+}
+
+interface UsageEntry {
+    sessionId: string;
+    endpoint: string;
+    method: string;
+    timestamp: number;
+    responseSize: number;
+    signature: string;
+}
+/**
+ * AggregatorService — Accumulates signed usage logs into a Merkle tree
+ * and triggers zk-SNARK proof generation when the threshold is reached.
+ *
+ * Architecture:
+ *   1. Facilitator logs each x402 API call to the aggregator
+ *   2. Aggregator builds a Merkle tree of log hashes
+ *   3. When threshold is reached, the proving pipeline is triggered
+ *   4. The proof + Merkle root are submitted to ZKUsageVerifier.sol
+ *
+ * For production: replace in-memory maps with Redis for persistence
+ * PRD §7.2 — ZKVUB Off-Chain Aggregation
+ */
+declare class AggregatorService {
+    private logs;
+    private merkleRoots;
+    private settlementThreshold;
+    constructor(config?: {
+        settlementThreshold?: number;
+    });
+    /**
+     * Append a signed usage entry
+     */
+    addEntry(entry: UsageEntry): {
+        totalEntries: number;
+        thresholdReached: boolean;
+    };
+    /**
+     * Build a Merkle tree from session's usage logs
+     * Returns the Merkle root hash
+     */
+    buildMerkleTree(sessionId: string): string;
+    /**
+     * Get circuit inputs for zk-SNARK proving
+     * These inputs are passed to the Circom circuit
+     */
+    getCircuitInputs(sessionId: string): {
+        callCount: number;
+        merkleRoot: string;
+        windowStart: number;
+        windowEnd: number;
+        logHashes: string[];
+    };
+    /**
+     * Clear entries for a settled session window
+     */
+    clearSettledEntries(sessionId: string, windowEnd: number): void;
+    /**
+     * Get aggregation stats for monitoring
+     */
+    getStats(): {
+        sessions: number;
+        totalEntries: number;
+        pendingSettlements: number;
+    };
+    /**
+     * Hash a single usage entry (leaf in the Merkle tree)
+     */
+    private hashEntry;
+    /**
+     * Compute Merkle root from leaf hashes
+     */
+    private computeMerkleRoot;
+}
+
+interface RedisUsageStoreConfig {
+    url: string;
+    keyPrefix?: string;
+    ttlSeconds?: number;
+}
+interface PersistedUsageEntry {
+    sessionId: string;
+    signer?: string;
+    endpoint: string;
+    method: string;
+    timestamp: number;
+    amount?: string;
+    settlementTxHash?: string | null;
+}
+declare class RedisUsageStore {
+    private readonly config;
+    private readonly client;
+    private connected;
+    constructor(config: RedisUsageStoreConfig);
+    connect(): Promise<void>;
+    appendUsage(entry: PersistedUsageEntry): Promise<void>;
+    getUsageCount(sessionId: string): Promise<number>;
+    getUsageEntries(sessionId: string, limit?: number): Promise<PersistedUsageEntry[]>;
+    setLatestSettlementTx(sessionId: string, txHash: string): Promise<void>;
+    getLatestSettlementTx(sessionId: string): Promise<string | null>;
+    stop(): Promise<void>;
+}
+
+interface ProofOrchestratorConfig extends UsageServiceConfig {
+    /** Max retries for proof submission (default: 3) */
+    maxRetries?: number;
+    /** Backoff delays in ms between retries (default: [2000, 5000, 15000]) */
+    retryDelays?: number[];
+    /** Auto-submit threshold: generate + submit proof when a session reaches this many calls */
+    autoSubmitThreshold?: number;
+    /** Settlement window duration in seconds (default: 3600 = 1 hour) */
+    windowDurationSeconds?: number;
+}
+type ProofStatus = "pending" | "generating" | "submitting" | "settled" | "failed";
+interface ProofJob {
+    sessionId: string;
+    windowEnd: number;
+    windowStart: number | null;
+    callCount: string | null;
+    settlementAmount: string | null;
+    status: ProofStatus;
+    attempts: number;
+    nullifier: string | null;
+    txHash: string | null;
+    error: string | null;
+    createdAt: number;
+    lastAttemptAt: number;
+}
+/**
+ * ProofOrchestrator coordinates the full ZKVUB settlement pipeline:
+ *
+ * 1. Monitor usage aggregation counts per session
+ * 2. When threshold is reached, freeze window and generate proof
+ * 3. Submit proof on-chain with deterministic retry
+ * 4. Track nullifiers to prevent double-settlement
+ * 5. Clean up after successful settlement
+ */
+declare class ProofOrchestrator {
+    private readonly usageService;
+    private readonly config;
+    /**
+     * Nullifiers that have been submitted — prevents double-settlement.
+     * Key: nullifier hash, Value: settlement timestamp
+     */
+    private readonly settledNullifiers;
+    /** Active proof jobs indexed by `sessionId:windowEnd` */
+    private readonly activeJobs;
+    /** Completed job history (last 200) */
+    private readonly jobHistory;
+    /** Interval for auto-submit checks */
+    private autoCheckInterval;
+    constructor(config?: ProofOrchestratorConfig);
+    /**
+     * Records usage and auto-triggers proof+submission when threshold is reached
+     */
+    recordUsage(sessionId: string, callData: {
+        endpoint: string;
+        method: string;
+        timestamp: number;
+        responseSize?: number;
+    }): Promise<void>;
+    /**
+     * Manually triggers proof generation + submission for a session
+     */
+    generateAndSubmit(sessionId: string): Promise<ProofJob>;
+    /**
+     * Execute a proof job with deterministic retry
+     */
+    private executeJob;
+    /**
+     * Move a job from active to history
+     */
+    private archiveJob;
+    /**
+     * Start auto-submit monitoring (polls every 30s)
+     */
+    startAutoSubmit(): void;
+    /**
+     * Stop auto-submit monitoring
+     */
+    stop(): void;
+    /**
+     * Get current active proof jobs
+     */
+    getActiveJobs(): ProofJob[];
+    /**
+     * Get completed job history
+     */
+    getJobHistory(limit?: number): ProofJob[];
+    /**
+     * Check if a nullifier has already been settled
+     */
+    isNullifierSettled(nullifier: string): boolean;
+    /**
+     * Get the underlying UsageService for direct access
+     */
+    getUsageService(): UsageService;
+}
+
+interface AxelarTransportConfig {
+    /** Axelar Gateway contract address on source chain */
+    gatewayAddress: `0x${string}`;
+    /** Axelar Gas Service contract address for prepaying gas */
+    gasServiceAddress: `0x${string}`;
+    /** RPC URL for source chain */
+    rpcUrl: string;
+    /** Private key for signing dispatch transactions */
+    privateKey: `0x${string}`;
+    /** Source chain ID */
+    chainId?: number;
+    /** MirrorRegistry address on destination chain */
+    mirrorRegistryAddress: `0x${string}`;
+}
+interface DispatchResult {
+    transactionHash: `0x${string}`;
+    messageId: string;
+    route: "axelar";
+    destinationChain: string;
+    gasEstimate: bigint;
+}
+/**
+ * AxelarTransport — Dispatches cross-chain GMP messages via Axelar Network.
+ *
+ * Flow:
+ * 1. Encode mirror payload (subscriber, tokenId, planId, tier, expiration, timestamp)
+ * 2. Estimate gas via Axelar Gas Service
+ * 3. Pre-pay gas via payNativeGasForContractCall
+ * 4. Call gateway.callContract() to dispatch to destination MirrorRegistry
+ */
+declare class AxelarTransport {
+    private readonly config;
+    private readonly chainId;
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly signerAddress;
+    constructor(config: AxelarTransportConfig);
+    /**
+     * Dispatch a cross-chain mirror update via Axelar GMP
+     */
+    dispatch(destinationChainId: number, payload: `0x${string}`, refundAddress: `0x${string}`, destinationAddressOverride?: `0x${string}`): Promise<DispatchResult>;
+    /**
+     * Get the estimated gas cost for a dispatch
+     */
+    estimateGas(destinationChainId: number, payload: `0x${string}`, destinationAddressOverride?: `0x${string}`): Promise<bigint>;
+    /**
+     * Get signer's gas balance (for alert monitoring)
+     */
+    getSignerBalance(): Promise<bigint>;
+}
+
+interface CCIPTransportConfig {
+    /** CCIP Router contract address on source chain */
+    routerAddress: `0x${string}`;
+    /** RPC URL for source chain */
+    rpcUrl: string;
+    /** Private key for signing dispatch transactions */
+    privateKey: `0x${string}`;
+    /** Source chain ID */
+    chainId?: number;
+    /** MirrorRegistry address on destination chain */
+    mirrorRegistryAddress: `0x${string}`;
+    /** LINK token address for fee payment (if using LINK) */
+    linkTokenAddress?: `0x${string}`;
+    /** Gas limit for destination execution */
+    gasLimit?: bigint;
+}
+interface CCIPDispatchResult {
+    transactionHash: `0x${string}`;
+    messageId: string;
+    route: "ccip";
+    destinationChainSelector: bigint;
+    fee: bigint;
+}
+/**
+ * CCIPTransport — Fallback cross-chain transport via Chainlink CCIP.
+ *
+ * Used when Axelar dispatch fails. Sends CCIP messages with:
+ * - EVM2AnyMessage encoding
+ * - Native gas fee payment (ETH)
+ * - Configurable destination gas limit
+ */
+declare class CCIPTransport {
+    private readonly config;
+    private readonly chainId;
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly signerAddress;
+    private readonly gasLimit;
+    constructor(config: CCIPTransportConfig);
+    /**
+     * Dispatch a cross-chain mirror update via Chainlink CCIP
+     */
+    dispatch(destinationChainId: number, payload: `0x${string}`, refundAddress: `0x${string}`, destinationAddressOverride?: `0x${string}`): Promise<CCIPDispatchResult>;
+    /**
+     * Build a CCIP EVM2AnyMessage
+     */
+    private buildMessage;
+    /**
+     * Estimate the CCIP fee for a dispatch
+     */
+    estimateFee(destinationChainId: number, payload: `0x${string}`, destinationAddressOverride?: `0x${string}`): Promise<bigint>;
+    /**
+     * Get signer's gas balance (for alert monitoring)
+     */
+    getSignerBalance(): Promise<bigint>;
+}
+
+interface BillingKeeperConfig {
+    /** RPC URL for the chain */
+    rpcUrl: string;
+    /** Chain ID */
+    chainId?: number;
+    /** Private key for the keeper signer (pays gas for execute calls) */
+    privateKey: `0x${string}`;
+    /** Polling interval in ms (default: 60000 = 1 minute) */
+    intervalMs?: number;
+    /** Max subscriptions to process per batch (default: 20) */
+    batchSize?: number;
+    /** How many seconds before expiry to trigger renewal (default: 86400 = 1 day) */
+    renewalBufferSeconds?: number;
+}
+interface RenewalResult {
+    tokenId: bigint;
+    subscriber: string;
+    txHash: `0x${string}`;
+    success: boolean;
+    error?: string;
+}
+/**
+ * BillingKeeper — Automated subscription renewal service.
+ *
+ * Polls SubscriptionRegistry for subscriptions nearing expiry,
+ * then calls ERC7579AutopayModule.execute() to pull the renewal
+ * payment from the subscriber's smart account.
+ *
+ * Architecture:
+ *   1. Poll registry for subscriptions expiring within `renewalBufferSeconds`
+ *   2. For each, check that the subscriber has an installed AutopayModule
+ *   3. Call execute() on the module to trigger the payment pull
+ *   4. Log results and emit renewal events
+ *
+ * PRD MEAP-004 — Automated Renewal Execution
+ */
+declare class BillingKeeper {
+    private readonly chainId;
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly signerAddress;
+    private readonly intervalMs;
+    private readonly batchSize;
+    private readonly renewalBufferSeconds;
+    private readonly registryAddress;
+    private readonly autopayModuleAddress;
+    private pollTimer;
+    private processing;
+    private renewalLog;
+    private callbacks;
+    constructor(config: BillingKeeperConfig);
+    /**
+     * Register a callback for renewal events
+     */
+    onRenewal(callback: (result: RenewalResult) => void): () => void;
+    /**
+     * Start the keeper polling loop
+     */
+    start(): void;
+    /**
+     * Stop the keeper
+     */
+    stop(): void;
+    /**
+     * Get renewal history
+     */
+    getRenewalLog(limit?: number): RenewalResult[];
+    /**
+     * Get keeper stats
+     */
+    getStats(): {
+        running: boolean;
+        totalRenewals: number;
+        successfulRenewals: number;
+        failedRenewals: number;
+    };
+    /**
+     * Poll for subscriptions needing renewal
+     */
+    private poll;
+    /**
+     * Find subscriptions expiring between now and the renewal deadline
+     */
+    private findExpiringSubscriptions;
+    /**
+     * Process a single subscription renewal
+     */
+    private processRenewal;
+    /**
+     * Check if AutopayModule is installed for a subscriber
+     */
+    private checkAutopayInstalled;
+    /**
+     * Log a renewal result
+     */
+    private logRenewal;
+}
+
+declare const PROTOCOL_EVENT_SCHEMA_VERSION = "2026-03-09.1";
+type ProtocolEventName = "subscription.minted" | "subscription.renewed" | "subscription.renewal_failed" | "subscription.cancelled" | "proof.generated" | "proof.submitted" | "proof.settled" | "invoice.issued" | "invoice.delivery_failed" | "invoice.paid";
+type ProtocolEventSource = "facilitator" | "dashboard" | "contracts" | "ops";
+interface ProtocolEvent<TPayload = Record<string, unknown>> {
+    schemaVersion: string;
+    name: ProtocolEventName;
+    source: ProtocolEventSource;
+    occurredAt: string;
+    idempotencyKey: string;
+    chainId?: number;
+    payload: TPayload;
+}
+declare function buildEventIdempotencyKey(name: ProtocolEventName, uniqueParts: Array<string | number | bigint>): string;
+declare function createProtocolEvent<TPayload>(name: ProtocolEventName, payload: TPayload, options: {
+    source: ProtocolEventSource;
+    idempotencyKey: string;
+    chainId?: number;
+    occurredAt?: string | number | Date;
+}): ProtocolEvent<TPayload>;
+declare function mapProtocolEventToBillingType(name: ProtocolEventName): "SUBSCRIPTION_MINTED" | "SUBSCRIPTION_RENEWED" | "SUBSCRIPTION_CANCELLED" | "PAYMENT_FAILED";
+
+export { type ActivateSubscriptionInput, type ActivateSubscriptionResult, AggregatorService, ArcenApiError, ArcenClient, type ArcenClientConfig, AxelarTransport, type AxelarTransportConfig, BillingKeeper, type BillingKeeperConfig, type CCIPDispatchResult, CCIPTransport, type CCIPTransportConfig, type DispatchResult, type EmailConfig, EmailService, type EmailTemplate, EventListenerService, type IdentifyInput, InMemoryNonceStore, type LitAccessCondition, type LitConfig, LitProtocolService, type NonceStore, PROTOCOL_EVENT_SCHEMA_VERSION, type PersistedUsageEntry, type ProofMode, ProofOrchestrator, type ProofOrchestratorConfig, type ProtocolEvent, type ProtocolEventName, type ProtocolEventSource, type RedisLike, RedisNonceStore, RedisUsageStore, type RedisUsageStoreConfig, type SettleForSignerInput, SettlementService, type SettlementWriteResult, type SettlementWriterConfig, SettlementWriterService, type SubscriptionEventData, type SubscriptionEventType, type TrackEventInput, UsageProofError, type UsageProofErrorCode, UsageProofErrorCodes, UsageService, type UsageServiceConfig, type WebhookConfig, type WebhookDeliveryLog, type WebhookPayload, WebhookService, type X402MiddlewareOptions, buildEventIdempotencyKey, createProtocolEvent, mapProtocolEventToBillingType, verifyWebhookSignature, x402Middleware };