payid 0.5.9 → 1.0.0

package/dist/index.d.ts

@@ -1,46 +1,122 @@
-import { RuleContext, RuleConfig, RuleResult } from 'payid-types';
-import { R as RuleSource } from './types-B8pJQdMQ.js';
-import { U as UserOperation } from './index-C1DHMQA0.js';
-export { i as server } from './index-C1DHMQA0.js';
+import { P as PayIDClient$1 } from './index-CsynGAGv.js';
+export { i as client } from './index-CsynGAGv.js';
+import { Z as ZGStorage, P as PayIDServer$1, U as UserOperation } from './index-DSxDlF9J.js';
+export { i as server, z as storage } from './index-DSxDlF9J.js';
 import { ethers } from 'ethers';
-export { i as sessionPolicy } from './index-BQQnMG2H.js';
-export { i as rule } from './index-Dj9IEios.js';
-export { i as issuer } from './index-2JCvey4-.js';
-export { i as context } from './index-BEvnPzzt.js';
-export { i as client } from './index-BPJ_oOfy.js';
-import './types-BmMf7udp.js';
+import { R as ResolverOptions, e as RuleSource, c as RuleResult, a as DecisionProof } from './types-i4eTkhWa.js';
+export { D as DecisionPayload, b as RuleDecisionDebug, d as RuleResultDebug, f as RuleTraceEntry } from './types-i4eTkhWa.js';
+import { b as RuleConfig } from './rule-a_5ed-93.js';
+export { A as AnyRule, M as MultiConditionRule, N as NestedRule, R as Rule, a as RuleCondition, S as SimpleRule, i as isMultiConditionRule, c as isNestedRule, d as isSimpleRule } from './rule-a_5ed-93.js';
+import { R as RuleContext } from './context.v1-C1m-tz0o.js';
+export { C as ContextV1, P as PayIdContext, T as TxContext } from './context.v1-C1m-tz0o.js';
+import { S as SessionPolicyV2 } from './types-D2o6XS7a.js';
+import { A as Attestation } from './context.v2-DIzPotmW.js';
+export { C as ContextV2, E as EnvContext, O as OracleContext, R as RiskContext, S as StateContext } from './context.v2-DIzPotmW.js';
+export { i as sessionPolicy } from './index-G_1SiZJo.js';
+export { i as rule } from './index-CubM9whW.js';
+export { i as issuer } from './index-CDnE3SGM.js';
+export { i as context } from './index-Dm2VdDEB.js';
+
+/**
+ * Create a client-safe PayID instance.
+ *
+ * - Safe for browser, mobile, and edge runtimes.
+ * - Signer is injected per-call in `evaluateAndProve`.
+ * - WASM rule engine with automatic TS fallback.
+ *
+ * @example
+ * ```ts
+ * // Browser / React
+ * const client = createPayIDClient({ debugTrace: true });
+ * const { result, proof } = await client.evaluateAndProve({
+ *   ..., signer: walletSigner
+ * });
+ * ```
+ */
+declare function createPayIDClient(params?: {
+    wasm?: Uint8Array;
+    debugTrace?: boolean;
+    resolverOptions?: ResolverOptions;
+}): PayIDClient$1;
+/**
+ * Create a server-side PayID instance.
+ *
+ * - For backends, bundlers, and relayers only — never ship to browser.
+ * - Signer is bound at construction time (server wallet).
+ * - Supports Context V2 with `trustedIssuers` enforcement.
+ * - Can build ERC-4337 UserOperations.
+ *
+ * @example
+ * ```ts
+ * // Backend / bundler
+ * const server = createPayIDServer({
+ *   signer: serverWallet,
+ *   trustedIssuers: new Set([TIME_ISSUER, RISK_ISSUER]),
+ * });
+ * const { result, proof } = await server.evaluateAndProve({ ... });
+ * const userOp = server.buildUserOperation({ proof, paymentType: "erc20", ... });
+ * ```
+ */
+declare function createPayIDServer(params: {
+    signer: ethers.Signer;
+    wasm?: Uint8Array;
+    debugTrace?: boolean;
+    trustedIssuers?: Set<string>;
+    storage?: ZGStorage;
+    resolverOptions?: ResolverOptions;
+}): PayIDServer$1;
+/**
+ * Alias for `createPayIDClient` — backwards-compatible entry point.
+ * Prefer `createPayIDClient` or `createPayIDServer` for clarity.
+ */
+declare function createPayID(params?: {
+    wasm?: Uint8Array;
+    debugTrace?: boolean;
+    resolverOptions?: ResolverOptions;
+}): PayIDClient$1;
 
 interface PayIDClient {
     /**
-     * Pure rule evaluation — client-safe, no signing
+     * Pure rule evaluation — no signing, client-safe.
      */
     evaluate(context: RuleContext, rule: RuleConfig | RuleSource): Promise<RuleResult>;
     /**
-     * Evaluate + generate EIP-712 Decision Proof
-     * Client sign sendiri pakai wallet mereka
+     * Evaluate rule + generate EIP-712 Decision Proof.
+     * Signer (wallet) diinjeksikan per-call — cocok untuk browser.
      */
     evaluateAndProve(params: {
         context: RuleContext;
+        /** Rule yang diambil dari chain (authority rule). */
         authorityRule: RuleConfig | RuleSource;
+        /** Override rule yang dipakai untuk evaluasi (opsional). */
         evaluationRule?: RuleConfig;
+        /** Session policy V2 (Channel A — receiver sign constraints). */
+        sessionPolicyV2?: SessionPolicyV2;
         payId: string;
         payer: string;
         receiver: string;
         asset: string;
         amount: bigint;
+        /** Wallet yang menandatangani proof. */
         signer: ethers.Signer;
         verifyingContract: string;
         ruleAuthority: string;
+        /** Override ruleSetHash di proof (untuk combined rules). */
+        ruleSetHashOverride?: string;
         ttlSeconds?: number;
+        chainId: number;
+        blockTimestamp: number;
+        /** EAS attestation UIDs untuk attestation-gated payments. */
+        attestationUIDs?: string[];
     }): Promise<{
         result: RuleResult;
-        proof: any | null;
+        proof: DecisionProof | null;
     }>;
 }
 interface PayIDServer {
     /**
-     * Evaluate + generate proof dengan trusted issuers
-     * Signer sudah di-inject saat construct PayIDServer
+     * Evaluate rule + generate proof.
+     * Signer sudah di-inject di constructor — tidak ada signer per-call.
      */
     evaluateAndProve(params: {
         context: RuleContext;
@@ -56,87 +132,346 @@ interface PayIDServer {
         ttlSeconds?: number;
         chainId: number;
         blockTimestamp: number;
+        attestationUIDs?: string[];
     }): Promise<{
         result: RuleResult;
-        proof: any | null;
+        proof: DecisionProof | null;
     }>;
     /**
-     * Build ERC-4337 UserOperation dari Decision Proof
-     * Server/bundler only
+     * Build ERC-4337 UserOperation dari Decision Proof.
+     * Dipakai oleh bundler/relayer untuk kirim transaksi.
      */
     buildUserOperation(params: {
-        proof: any;
+        proof: DecisionProof;
         smartAccount: string;
         nonce: string;
-        gas: any;
+        gas: {
+            callGasLimit: string;
+            verificationGasLimit: string;
+            preVerificationGas: string;
+            maxFeePerGas: string;
+            maxPriorityFeePerGas: string;
+        };
         targetContract: string;
         paymasterAndData?: string;
         attestationUIDs?: string[];
+        paymentType?: "eth" | "erc20";
     }): UserOperation;
 }
 
+interface ReverseResolutionResult {
+    payId: string;
+    owner: string;
+    activeRuleHash?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ReverseResolutionOptions extends ResolverOptions {
+    registryUrl?: string;
+    timeoutMs?: number;
+}
 /**
- * Create a PayID policy engine instance backed by a WASM rule evaluator.
- *
- * ## Responsibility
- *
- * - Holds the WASM binary used for rule execution
- * - Defines the trust boundary for context attestation verification
- * - Acts as the primary entry point for PayID rule evaluation
+ * Reverse resolve a wallet address to its registered PayID.
  *
- * ## Trust model
+ * Queries the 0G Storage reverse index or a fallback registry HTTP endpoint.
  *
- * - If `trustedIssuers` is provided, Context V2 attestation
- *   verification is ENFORCED.
- * - If `trustedIssuers` is omitted, the engine runs in
- *   legacy (Context V1) mode without cryptographic verification.
- *
- * ## Environment
- *
- * This class is safe to instantiate in:
- * - Browsers
- * - Mobile apps
- * - Edge runtimes
- * - Backend services
+ * @example
+ * ```ts
+ * const { payId } = await reverseResolvePayID(
+ *   "0x1234...",
+ *   { registryUrl: "https://registry.pay.id/v1" }
+ * );
+ * console.log(payId); // "alice.pay.id"
+ * ```
+ */
+declare function reverseResolvePayID(address: string, options?: ReverseResolutionOptions): Promise<ReverseResolutionResult | null>;
+/**
+ * Batch reverse resolve multiple addresses at once.
+ * Useful for enriching contact lists or transaction history.
+ */
+declare function batchReverseResolve(addresses: string[], options?: ReverseResolutionOptions): Promise<Map<string, ReverseResolutionResult | null>>;
+
+interface CachedRule {
+    key: string;
+    config: Record<string, unknown>;
+    timestamp: number;
+    sourceUri: string;
+    sizeBytes: number;
+}
+declare const ruleCache: {
+    get: (key: string) => Promise<CachedRule | null>;
+    set: (value: CachedRule) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    getAll: () => Promise<CachedRule[]>;
+    clear: () => Promise<void>;
+};
+interface CachedContact {
+    payId: string;
+    address: string;
+    name: string;
+    avatar?: string;
+    addedAt: number;
+    note?: string;
+    reputation?: number;
+    isBlacklisted?: boolean;
+}
+declare const contactCache: {
+    get: (payId: string) => Promise<CachedContact | null>;
+    set: (value: CachedContact) => Promise<void>;
+    delete: (payId: string) => Promise<void>;
+    getAll: () => Promise<CachedContact[]>;
+    findByAddress: (address: string) => Promise<CachedContact[]>;
+    findByName: (name: string) => Promise<CachedContact[]>;
+};
+type DraftStatus = "draft" | "queued" | "syncing" | "sent" | "failed";
+interface DraftPayment {
+    id?: number;
+    toPayId: string;
+    toAddress?: string;
+    amount: string;
+    asset: string;
+    note?: string;
+    status: DraftStatus;
+    createdAt: number;
+    updatedAt: number;
+    proofHash?: string;
+    txHash?: string;
+    error?: string;
+}
+declare const draftCache: {
+    get: (id: number) => Promise<DraftPayment | null>;
+    set: (value: DraftPayment) => Promise<void>;
+    delete: (id: number) => Promise<void>;
+    getAll: () => Promise<DraftPayment[]>;
+    getPending: () => Promise<DraftPayment[]>;
+    getFailed: () => Promise<DraftPayment[]>;
+};
+interface CachedTx {
+    txHash: string;
+    from: string;
+    to: string;
+    amount: string;
+    asset: string;
+    payId?: string;
+    timestamp: number;
+    status: "pending" | "confirmed" | "failed";
+    fee?: string;
+    blockNumber?: number;
+}
+declare const historyCache: {
+    get: (txHash: string) => Promise<CachedTx | null>;
+    set: (value: CachedTx) => Promise<void>;
+    delete: (txHash: string) => Promise<void>;
+    getAll: () => Promise<CachedTx[]>;
+};
+interface CacheStats {
+    rules: number;
+    contacts: number;
+    drafts: number;
+    history: number;
+    totalSizeEstimate: number;
+}
+declare function getCacheStats(): Promise<CacheStats>;
+declare function clearAllCache(): Promise<void>;
+
+interface DeployRuleOptions {
+    ruleFile: string;
+    ipfsGateway?: string;
+    ruleAuthorityAddress: string;
+    chainId: number;
+    privateKey: string;
+    rpcUrl: string;
+    outputJson?: string;
+}
+interface DeployRuleResult {
+    ruleHash: string;
+    ipfsCid?: string;
+    ruleId?: string;
+    txHash: string;
+    status: "success" | "error";
+    error?: string;
+}
+/**
+ * Deploy a rule JSON file to IPFS and register it with RuleAuthority.
  *
- * @param wasm
- *   Compiled PayID WASM rule engine binary.
+ * @example
+ * ```bash
+ * npx payid deploy-rule ./my-rule.json \
+ *   --authority 0x1234... \
+ *   --chain 31337 \
+ *   --key $PRIVATE_KEY \
+ *   --rpc http://127.0.0.1:8545
+ * ```
+ */
+declare function deployRule(options: DeployRuleOptions): Promise<DeployRuleResult>;
+
+interface VerifyProofOptions {
+    txHash: string;
+    rpcUrl: string;
+    payIDVerifierAddress: string;
+    expectedSigner?: string;
+}
+interface VerifyProofResult {
+    valid: boolean;
+    status: "verified" | "invalid" | "not_found" | "error";
+    details?: {
+        payId: string;
+        payer: string;
+        receiver: string;
+        amount: string;
+        asset: string;
+        decision: "ALLOW" | "REJECT";
+        timestamp: number;
+        nonce: string;
+        ruleAuthority: string;
+    };
+    error?: string;
+}
+/**
+ * Verify a Decision Proof on-chain by txHash.
  *
- * @param debugTrace
- *   Optional flag to enable decision trace generation for debugging.
+ * @example
+ * ```bash
+ * npx payid verify-proof 0xabc123... \
+ *   --verifier 0x5678... \
+ *   --rpc http://127.0.0.1:8545
+ * ```
+ */
+declare function verifyProof(options: VerifyProofOptions): Promise<VerifyProofResult>;
+
+declare function verifyAttestation(payload: object, proof: Attestation, trustedIssuers: Set<string>): void;
+
+/**
+ * Extended context for fiat payment rails.
+ * The WASM engine evaluates JSON loosely, so we use Record<string,any>
+ * for tx fields beyond the standard RuleContext shape.
+ */
+type FiatRuleContext = Omit<RuleContext, "tx" | "env"> & {
+    tx: Record<string, any>;
+    env: {
+        timestamp: number;
+    };
+};
+/**
+ * QRIS / fiat payment payload from a bank app or PSP.
+ */
+interface QRISPayload {
+    /** Transaction amount in smallest unit (e.g. IDR satang) */
+    amount: string;
+    /** ISO-4217 currency code, e.g. "IDR", "USD" */
+    currency: string;
+    /** Merchant ID or identifier */
+    merchantId: string;
+    /** Payment Service Provider code, e.g. "BANK_ABC" */
+    pspCode: string;
+    /** Optional POS terminal ID */
+    terminalId?: string;
+    /** Optional Merchant Category Code (ISO 18245) */
+    mcc?: string;
+    /** Optional linked wallet address */
+    userWallet?: string;
+}
+/**
+ * Result of evaluating a fiat payment against merchant rules.
+ */
+interface FiatEvaluationResult {
+    /** Whether the payment is allowed */
+    allowed: boolean;
+    /** EIP-712 Decision Proof (present when allowed) */
+    proof?: DecisionProof;
+    /** Rejection reason (present when not allowed) */
+    reason?: string;
+}
+/**
+ * FiatAdapter — bridge between traditional payment rails (QRIS, SWIFT, etc.)
+ * and the PAY.ID policy engine.
  *
- * @param trustedIssuers
- *   Optional set of trusted attestation issuer addresses.
+ * The adapter normalizes bank/PSP payloads into PAY.ID RuleContext,
+ * evaluates merchant rules, and returns a DecisionProof for bank verification.
  *
- *   When provided, Context V2 attestation verification is ENFORCED:
- *   - Only attestations issued by addresses in this set are accepted.
- *   - Missing, expired, or invalid attestations cause evaluation to fail.
+ * @example
+ * ```ts
+ * const adapter = new FiatAdapter();
  *
- *   When omitted, the engine runs in legacy (Context V1) mode
- *   without cryptographic verification.
+ * const { allowed, proof, reason } = await adapter.evaluatePayment(
+ *   {
+ *     amount: '150000',
+ *     currency: 'IDR',
+ *     merchantId: 'MID123',
+ *     pspCode: 'BANK_ABC',
+ *   },
+ *   'https://rules.example.com/merchant-rules.json',
+ *   walletSigner,
+ *   {
+ *     verifyingContract: '0x...',
+ *     ruleAuthority: '0x...',
+ *     chainId: 31337,
+ *   }
+ * );
+ * ```
+ */
+declare class FiatAdapter {
+    private readonly client;
+    constructor(debugTrace?: boolean, wasm?: Uint8Array);
+    /**
+     * Evaluate a fiat payment payload against merchant rules.
+     */
+    evaluatePayment(payload: QRISPayload, merchantRuleURI: string | RuleSource, signer: ethers.Signer, contractConfig: {
+        verifyingContract: string;
+        ruleAuthority: string;
+        chainId: number;
+    }): Promise<FiatEvaluationResult>;
+    /**
+     * Build a PAY.ID RuleContext from a fiat payload without evaluating.
+     * Useful for previewing or debugging rule logic.
+     */
+    buildContext(payload: QRISPayload): FiatRuleContext;
+}
+
+/**
+ * Compute USD equivalent of a token amount from a Chainlink-style price feed.
  *
- *   ⚠️ Important:
- *   - Do NOT pass an empty Set.
- *     An empty set means "no issuer is trusted" and will
- *     cause all attestations to be rejected.
+ * @param amount      Raw token amount (in token's smallest unit, e.g. wei for ETH, micro-USDC)
+ * @param decimals    Token decimals (e.g. 18 for ETH, 6 for USDC)
+ * @param priceInUsd  Price from oracle in USD with 8 decimals (e.g. 350000000000 = $3500.00)
+ * @returns USD value with 8 decimals
  *
- *   @example
- *   ```ts
- *   const trustedIssuers = new Set([
- *     TIME_ISSUER,
- *     STATE_ISSUER,
- *     ORACLE_ISSUER,
- *     RISK_ISSUER
- *   ]);
+ * @example
+ *   computeTxValueUsd(1_000_000n, 6, 100000000n)  // 1 USDC @ $1.00 → 100000000n ($1.00)
+ *   computeTxValueUsd(1000000000000000000n, 18, 350000000000n) // 1 ETH @ $3500 → 35000000000000000000n ($3500.00)
+ */
+declare function computeTxValueUsd(amount: bigint, decimals: number, priceInUsd: bigint): bigint;
+/**
+ * Format a USD value (8 decimals) to human-readable string.
  *
- *   const payid = new PayID(wasmBinary, debugTrace, trustedIssuers);
- *   ```
+ * @param usdValue  USD amount with 8 decimals
+ * @returns Formatted string like "$45.00"
  */
-declare function createPayID(params: {
-    wasm?: Uint8Array;
-    debugTrace?: boolean;
-    trustedIssuers?: Set<string>;
-}): PayIDClient & PayIDServer;
+declare function formatUsdValue(usdValue: bigint): string;
+/**
+ * Minimal Chainlink AggregatorV3 ABI for fetching price off-chain.
+ */
+declare const CHAINLINK_AGGREGATOR_ABI: readonly [{
+    readonly name: "latestRoundData";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "roundId";
+        readonly type: "uint80";
+    }, {
+        readonly name: "answer";
+        readonly type: "int256";
+    }, {
+        readonly name: "startedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "updatedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "answeredInRound";
+        readonly type: "uint80";
+    }];
+}];
 
 /**
  * @module eas
@@ -203,4 +538,4 @@ declare namespace eas {
   export { type eas_EASAttestation as EASAttestation, eas_EASClient as EASClient, type eas_EASClientOptions as EASClientOptions, eas_EAS_ADDRESSES as EAS_ADDRESSES };
 }
 
-export { type PayIDClient, type PayIDServer, createPayID, eas };
+export { Attestation, CHAINLINK_AGGREGATOR_ABI, type CacheStats, type CachedContact, type CachedRule, type CachedTx, DecisionProof, type DeployRuleOptions, type DeployRuleResult, type DraftPayment, type DraftStatus, FiatAdapter, type FiatEvaluationResult, type PayIDClient, type PayIDServer, type QRISPayload, ResolverOptions, type ReverseResolutionOptions, type ReverseResolutionResult, RuleConfig, RuleContext, RuleResult, type VerifyProofOptions, type VerifyProofResult, batchReverseResolve, clearAllCache, computeTxValueUsd, contactCache, createPayID, createPayIDClient, createPayIDServer, deployRule, draftCache, eas, formatUsdValue, getCacheStats, historyCache, reverseResolvePayID, ruleCache, verifyAttestation, verifyProof };