@pay-skill/sdk 0.1.1

package/dist/ows-signer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OWS (Open Wallet Standard) signer adapter.
+ *
+ * Wraps the @open-wallet-standard/core FFI module to implement the Pay
+ * Signer interface. OWS handles encrypted key storage + policy-gated signing;
+ * this adapter translates between Pay's (domain, types, value) EIP-712
+ * calling convention and OWS's JSON string convention.
+ *
+ * Priority: Pay's own CLI signer is #1, OWS is #2. OWS only activates when
+ * OWS_WALLET_ID is set AND @open-wallet-standard/core is installed. If the
+ * env var is set but the package is missing, creation fails loud with
+ * install instructions.
+ *
+ * Usage:
+ *   const signer = await OwsSigner.create({ walletId: "pay-my-agent" });
+ *   const wallet = new Wallet({ signer });
+ */
+import type { Signer } from "./signer.js";
+/** EIP-712 domain fields. */
+export interface TypedDataDomain {
+    name?: string;
+    version?: string;
+    chainId?: number | bigint;
+    verifyingContract?: string;
+}
+/** EIP-712 type definitions. */
+export interface TypedDataTypes {
+    [typeName: string]: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+/** Options for {@link OwsSigner.create}. */
+export interface OwsSignerOptions {
+    /** OWS wallet name or UUID (e.g. "pay-my-agent"). */
+    walletId: string;
+    /** Chain name - only used for logging, not passed to OWS. Default: "base". */
+    chain?: string;
+    /** OWS API key token (passed as passphrase to OWS signing calls). */
+    owsApiKey?: string;
+    /** @internal Inject OWS module for testing - bypasses dynamic import. */
+    _owsModule?: unknown;
+}
+/**
+ * Signer backed by the Open Wallet Standard.
+ *
+ * - Keys live in OWS's encrypted vault (~/.ows/wallets/), never in env vars.
+ * - Signing calls go through OWS FFI, which evaluates policy rules before signing.
+ * - Use the static {@link create} factory - the constructor is private because
+ *   address resolution requires a synchronous FFI call that must happen before
+ *   sign() can work.
+ */
+export declare class OwsSigner implements Signer {
+    #private;
+    private constructor();
+    /**
+     * Create an OwsSigner by resolving the wallet address from OWS.
+     *
+     * Lazily imports @open-wallet-standard/core so the module is only required
+     * when OWS is actually used (keeps it an optional peer dependency).
+     */
+    static create(options: OwsSignerOptions): Promise<OwsSigner>;
+    get address(): string;
+    sign(_hash: Uint8Array): Uint8Array;
+    /**
+     * Sign EIP-712 typed data via OWS FFI.
+     *
+     * This is the primary signing method for OWS. Pay's auth module should
+     * call this instead of sign() when an OwsSigner is detected.
+     */
+    signTypedData(domain: TypedDataDomain, types: TypedDataTypes, value: Record<string, unknown>): Promise<string>;
+    /** Prevent wallet ID / key leakage in serialization. */
+    toJSON(): Record<string, string>;
+}
+//# sourceMappingURL=ows-signer.d.ts.map

package/dist/ows-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ows-signer.d.ts","sourceRoot":"","sources":["../src/ows-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAwB1C,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAU,YAAW,MAAM;;IAMtC,OAAO;IAYP;;;;;OAKG;WACU,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC;IAqClE,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAQnC;;;;;OAKG;IACG,aAAa,CACjB,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC;IAuDlB,wDAAwD;IACxD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAOjC"}

package/dist/ows-signer.js

@@ -0,0 +1,130 @@
+/**
+ * OWS (Open Wallet Standard) signer adapter.
+ *
+ * Wraps the @open-wallet-standard/core FFI module to implement the Pay
+ * Signer interface. OWS handles encrypted key storage + policy-gated signing;
+ * this adapter translates between Pay's (domain, types, value) EIP-712
+ * calling convention and OWS's JSON string convention.
+ *
+ * Priority: Pay's own CLI signer is #1, OWS is #2. OWS only activates when
+ * OWS_WALLET_ID is set AND @open-wallet-standard/core is installed. If the
+ * env var is set but the package is missing, creation fails loud with
+ * install instructions.
+ *
+ * Usage:
+ *   const signer = await OwsSigner.create({ walletId: "pay-my-agent" });
+ *   const wallet = new Wallet({ signer });
+ */
+/**
+ * Signer backed by the Open Wallet Standard.
+ *
+ * - Keys live in OWS's encrypted vault (~/.ows/wallets/), never in env vars.
+ * - Signing calls go through OWS FFI, which evaluates policy rules before signing.
+ * - Use the static {@link create} factory - the constructor is private because
+ *   address resolution requires a synchronous FFI call that must happen before
+ *   sign() can work.
+ */
+export class OwsSigner {
+    #walletId;
+    #address;
+    #owsApiKey;
+    #ows;
+    constructor(walletId, address, owsModule, owsApiKey) {
+        this.#walletId = walletId;
+        this.#address = address;
+        this.#ows = owsModule;
+        this.#owsApiKey = owsApiKey;
+    }
+    /**
+     * Create an OwsSigner by resolving the wallet address from OWS.
+     *
+     * Lazily imports @open-wallet-standard/core so the module is only required
+     * when OWS is actually used (keeps it an optional peer dependency).
+     */
+    static async create(options) {
+        let owsModule;
+        if (options._owsModule) {
+            owsModule = options._owsModule;
+        }
+        else {
+            try {
+                // Dynamic string prevents TypeScript from statically resolving this
+                // optional peer dependency at compile time.
+                const moduleName = "@open-wallet-standard/core";
+                owsModule = (await import(moduleName));
+            }
+            catch {
+                throw new Error("OWS_WALLET_ID is set but @open-wallet-standard/core is not installed. " +
+                    "Install it with: npm install @open-wallet-standard/core");
+            }
+        }
+        const walletInfo = owsModule.getWallet(options.walletId);
+        const evmAccount = walletInfo.accounts.find((a) => a.chainId === "evm" || a.chainId.startsWith("eip155:"));
+        if (!evmAccount) {
+            throw new Error(`No EVM account found in OWS wallet '${options.walletId}'. ` +
+                `Available chains: ${walletInfo.accounts.map((a) => a.chainId).join(", ") || "none"}.`);
+        }
+        return new OwsSigner(options.walletId, evmAccount.address, owsModule, options.owsApiKey);
+    }
+    get address() {
+        return this.#address;
+    }
+    sign(_hash) {
+        throw new Error("OwsSigner does not support raw hash signing. " +
+            "OWS only supports EIP-712 typed data signing. " +
+            "Use CliSigner or RawKeySigner for operations that require sign().");
+    }
+    /**
+     * Sign EIP-712 typed data via OWS FFI.
+     *
+     * This is the primary signing method for OWS. Pay's auth module should
+     * call this instead of sign() when an OwsSigner is detected.
+     */
+    async signTypedData(domain, types, value) {
+        // 1. Derive primaryType: first key in types that is NOT "EIP712Domain".
+        const primaryType = Object.keys(types).filter((k) => k !== "EIP712Domain")[0] ?? "Request";
+        // 2. Build EIP712Domain type array dynamically from domain object fields.
+        const eip712DomainType = [];
+        if (domain.name !== undefined)
+            eip712DomainType.push({ name: "name", type: "string" });
+        if (domain.version !== undefined)
+            eip712DomainType.push({ name: "version", type: "string" });
+        if (domain.chainId !== undefined)
+            eip712DomainType.push({ name: "chainId", type: "uint256" });
+        if (domain.verifyingContract !== undefined)
+            eip712DomainType.push({
+                name: "verifyingContract",
+                type: "address",
+            });
+        // 3. Assemble full EIP-712 typed data structure.
+        const fullTypedData = {
+            types: { EIP712Domain: eip712DomainType, ...types },
+            primaryType,
+            domain,
+            message: value,
+        };
+        // 4. Serialize - handle BigInt values.
+        const json = JSON.stringify(fullTypedData, (_key, v) => typeof v === "bigint" ? v.toString() : v);
+        // 5. Call OWS FFI. Chain is always "evm" for EVM signing.
+        const result = this.#ows.signTypedData(this.#walletId, "evm", json, this.#owsApiKey);
+        // 6. Concatenate r+s+v into 65-byte Ethereum signature.
+        const sig = result.signature.startsWith("0x")
+            ? result.signature.slice(2)
+            : result.signature;
+        // If OWS already returns r+s+v (130 hex chars), use as-is.
+        if (sig.length === 130) {
+            return `0x${sig}`;
+        }
+        // Otherwise it's r+s (128 hex chars), append v.
+        const v = (result.recoveryId ?? 0) + 27;
+        return `0x${sig}${v.toString(16).padStart(2, "0")}`;
+    }
+    /** Prevent wallet ID / key leakage in serialization. */
+    toJSON() {
+        return { address: this.#address, walletId: this.#walletId };
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `OwsSigner { address: '${this.#address}', wallet: '${this.#walletId}' }`;
+    }
+}
+//# sourceMappingURL=ows-signer.js.map

package/dist/ows-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ows-signer.js","sourceRoot":"","sources":["../src/ows-signer.ts"],"names":[],"mappings":"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"}

package/dist/signer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Signer interface and implementations.
+ *
+ * Three modes:
+ * 1. CLI signer (default): subprocess call to `pay sign`
+ * 2. Raw key: from PAYSKILL_KEY environment variable (dev/testing only)
+ * 3. Custom: user provides a sign(hash) -> signature callback
+ */
+/** Abstract signer interface. */
+export interface Signer {
+    /** Sign a 32-byte hash. Returns 65-byte signature (r || s || v). */
+    sign(hash: Uint8Array): Uint8Array;
+    /** The signer's Ethereum address (0x-prefixed, checksummed). */
+    readonly address: string;
+}
+/** Signs via the `pay sign` CLI subprocess. */
+export declare class CliSigner implements Signer {
+    private readonly command;
+    readonly address: string;
+    constructor(command?: string, address?: string);
+    sign(hash: Uint8Array): Uint8Array;
+}
+/** Signs with a raw private key using viem. Dev/testing only. */
+export declare class RawKeySigner implements Signer {
+    private readonly _key;
+    readonly address: string;
+    constructor(key?: string);
+    sign(hash: Uint8Array): Uint8Array;
+    /** Async sign — preferred over sync sign(). */
+    signAsync(hash: Uint8Array): Promise<Uint8Array>;
+}
+/** Delegates signing to a user-provided callback. */
+export declare class CallbackSigner implements Signer {
+    private readonly callback;
+    readonly address: string;
+    constructor(callback: (hash: Uint8Array) => Uint8Array, address?: string);
+    sign(hash: Uint8Array): Uint8Array;
+}
+/** Factory for creating signers. */
+export declare function createSigner(mode?: "cli" | "raw" | "custom", options?: {
+    command?: string;
+    key?: string;
+    address?: string;
+    callback?: (hash: Uint8Array) => Uint8Array;
+}): Signer;
+//# sourceMappingURL=signer.d.ts.map

package/dist/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,iCAAiC;AACjC,MAAM,WAAW,MAAM;IACrB,oEAAoE;IACpE,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,+CAA+C;AAC/C,qBAAa,SAAU,YAAW,MAAM;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,SAAQ,EAAE,OAAO,SAAK;IAgBzC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;CASnC;AAED,iEAAiE;AACjE,qBAAa,YAAa,YAAW,MAAM;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,GAAG,CAAC,EAAE,MAAM;IAYxB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;IAelC,+CAA+C;IACzC,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAMvD;AAED,qDAAqD;AACrD,qBAAa,cAAe,YAAW,MAAM;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGvB,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,EAC1C,OAAO,SAAK;IAMd,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;CAGnC;AAED,oCAAoC;AACpC,wBAAgB,YAAY,CAC1B,IAAI,GAAE,KAAK,GAAG,KAAK,GAAG,QAAgB,EACtC,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAC;CACxC,GACL,MAAM,CAcR"}

package/dist/signer.js

@@ -0,0 +1,112 @@
+/**
+ * Signer interface and implementations.
+ *
+ * Three modes:
+ * 1. CLI signer (default): subprocess call to `pay sign`
+ * 2. Raw key: from PAYSKILL_KEY environment variable (dev/testing only)
+ * 3. Custom: user provides a sign(hash) -> signature callback
+ */
+import { execFileSync } from "node:child_process";
+import { privateKeyToAccount, sign as viemSign, serializeSignature, } from "viem/accounts";
+/** Signs via the `pay sign` CLI subprocess. */
+export class CliSigner {
+    command;
+    address;
+    constructor(command = "pay", address = "") {
+        this.command = command;
+        if (address) {
+            this.address = address;
+        }
+        else {
+            try {
+                this.address = execFileSync(this.command, ["address"], {
+                    encoding: "utf-8",
+                    timeout: 10_000,
+                }).trim();
+            }
+            catch {
+                this.address = "";
+            }
+        }
+    }
+    sign(hash) {
+        const hexHash = Buffer.from(hash).toString("hex");
+        const result = execFileSync(this.command, ["sign"], {
+            input: hexHash,
+            encoding: "utf-8",
+            timeout: 30_000,
+        });
+        return Buffer.from(result.trim(), "hex");
+    }
+}
+/** Signs with a raw private key using viem. Dev/testing only. */
+export class RawKeySigner {
+    _key;
+    address;
+    constructor(key) {
+        const rawKey = key ?? process.env.PAYSKILL_KEY ?? "";
+        if (!rawKey) {
+            throw new Error("No key provided and PAYSKILL_KEY not set");
+        }
+        this._key = rawKey.startsWith("0x")
+            ? rawKey
+            : `0x${rawKey}`;
+        const account = privateKeyToAccount(this._key);
+        this.address = account.address;
+    }
+    sign(hash) {
+        // viem's sign() does raw ECDSA signing (no EIP-191 prefix)
+        const hashHex = ("0x" + Buffer.from(hash).toString("hex"));
+        // sign() is async but Signer interface is sync — we use the sync internal
+        // For the sync interface, we need a workaround. Since RawKeySigner is
+        // dev/testing only, we'll do a sync computation via signSync.
+        // viem doesn't expose sync sign, but we can construct manually.
+        // Use the async path via signAsync helper pattern.
+        throw new Error("RawKeySigner.sign() is synchronous but viem signing is async. " +
+            "Use RawKeySigner.signAsync() or use buildAuthHeaders() directly with the private key.");
+    }
+    /** Async sign — preferred over sync sign(). */
+    async signAsync(hash) {
+        const hashHex = ("0x" + Buffer.from(hash).toString("hex"));
+        const raw = await viemSign({ hash: hashHex, privateKey: this._key });
+        const sigHex = serializeSignature(raw);
+        return hexToBytes(sigHex);
+    }
+}
+/** Delegates signing to a user-provided callback. */
+export class CallbackSigner {
+    callback;
+    address;
+    constructor(callback, address = "") {
+        this.callback = callback;
+        this.address = address;
+    }
+    sign(hash) {
+        return this.callback(hash);
+    }
+}
+/** Factory for creating signers. */
+export function createSigner(mode = "cli", options = {}) {
+    switch (mode) {
+        case "cli":
+            return new CliSigner(options.command, options.address);
+        case "raw":
+            return new RawKeySigner(options.key);
+        case "custom":
+            if (!options.callback) {
+                throw new Error("custom signer requires a callback");
+            }
+            return new CallbackSigner(options.callback, options.address);
+        default:
+            throw new Error(`Unknown signer mode: ${mode}`);
+    }
+}
+function hexToBytes(hex) {
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+//# sourceMappingURL=signer.js.map

package/dist/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"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"}

package/dist/wallet.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Wallet — high-level write client for agents.
+ * Wraps PayClient with private key signing and balance tracking.
+ *
+ * This is the primary entry point for the playground and agent integrations.
+ * The PayClient is lower-level (HTTP only); Wallet adds signing + state.
+ */
+export interface WalletOptions {
+    privateKey: string;
+    chain: string;
+    apiUrl: string;
+    routerAddress: string;
+    /** Numeric chain ID for EIP-712 domain. If omitted, parsed from `chain`. */
+    chainId?: number;
+}
+export interface FundLinkOptions {
+    messages?: unknown[];
+    agentName?: string;
+}
+export interface PermitResult {
+    nonce: string;
+    deadline: number;
+    v: number;
+    r: string;
+    s: string;
+}
+export declare class Wallet {
+    readonly address: string;
+    private readonly _privateKey;
+    private readonly _apiUrl;
+    private readonly _chain;
+    private readonly _chainId;
+    private readonly _routerAddress;
+    private readonly _account;
+    /** URL path prefix extracted from apiUrl (e.g., "/api/v1"). */
+    private readonly _basePath;
+    /** Cached contracts response. */
+    private _contractsCache;
+    constructor(options: WalletOptions);
+    private get _authConfig();
+    /** Build authenticated fetch headers for an API request. */
+    private _authFetch;
+    /** Get USDC balance in human-readable units (e.g., 142.50). */
+    balance(): Promise<number>;
+    /**
+     * Sign an EIP-2612 permit for a given spender and amount.
+     * Uses the server's /permit/prepare endpoint to get the nonce and hash,
+     * then signs the hash locally.
+     * @param flow — "direct" or "tab" (used to look up the spender contract address)
+     * @param amount — micro-USDC amount
+     */
+    signPermit(flow: string, amount: number): Promise<PermitResult>;
+    /** Send a direct payment. Auto-signs permit if not provided. */
+    payDirect(to: string, amount: number, memo: string, options?: {
+        permit?: PermitResult;
+    }): Promise<{
+        tx_hash: string;
+        status: string;
+    }>;
+    /** Create a one-time fund link via the server. Returns the dashboard URL. */
+    createFundLink(options?: FundLinkOptions): Promise<string>;
+    /** Create a one-time withdraw link via the server. Returns the dashboard URL. */
+    createWithdrawLink(options?: FundLinkOptions): Promise<string>;
+    /** Register a webhook for this wallet. */
+    registerWebhook(url: string, events: string[], secret?: string): Promise<{
+        id: string;
+    }>;
+    /** Open a tab with a provider (positional or object form). */
+    openTab(providerOrOpts: string | {
+        to: string;
+        limit: number;
+        perUnit: number;
+        permit?: PermitResult;
+    }, amount?: number, maxChargePerCall?: number, options?: {
+        permit?: PermitResult;
+    }): Promise<{
+        id: string;
+        tab_id: string;
+    }>;
+    /** Charge a tab (provider-side). */
+    chargeTab(tabId: string, amountOrOpts: number | {
+        amount: number;
+        cumulative: number;
+        callCount: number;
+        providerSig: string;
+    }): Promise<{
+        status: string;
+    }>;
+    /** Close a tab. */
+    closeTab(tabId: string, options?: {
+        finalAmount?: number;
+        providerSig?: string;
+    }): Promise<{
+        status: string;
+    }>;
+    /** Fetch contract addresses from the API (public, no auth). */
+    getContracts(): Promise<{
+        router: string;
+        tab: string;
+        direct: string;
+        fee: string;
+        usdc: string;
+        chainId: number;
+    }>;
+    /** Sign a tab charge (provider-side EIP-712 signature). */
+    signTabCharge(contractAddr: string, tabId: string, cumulativeUnits: bigint | number, callCount: number): Promise<string>;
+    /** Sign a raw hash with the wallet's private key. */
+    private _signHash;
+}
+/** PrivateKeySigner — for manual EIP-712 signing in the playground. */
+export declare class PrivateKeySigner {
+    private readonly _account;
+    readonly address: string;
+    constructor(privateKey: string);
+    /** Sign EIP-712 typed data. Returns hex signature. */
+    signTypedData(domain: Record<string, unknown>, types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>, message: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=wallet.d.ts.map

package/dist/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"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"}