@droplinked_inc/web3-kit 0.1.0

package/dist/tokens.js

@@ -0,0 +1,215 @@
+/**
+ * Hard-coded registry of vetted token contract addresses per chain.
+ *
+ * The single most important defence in this package: when a caller
+ * (e.g. a checkout component) says "the user is paying in USDC on
+ * Polygon", the address used in the on-chain call MUST come from this
+ * table — never from a backend response, never from a URL parameter,
+ * never from local storage. Every address has been cross-checked
+ * against the chain's canonical block explorer and the issuer's
+ * authoritative documentation.
+ *
+ * If a caller supplies their own address for a known symbol via
+ * `assertCanonicalTokenAddress`, the address is compared (case-
+ * insensitive) against the registry and rejected on mismatch with
+ * `TokenAddressMismatchError`. This blocks the "passing a malicious
+ * token addr that mimics USDC" class of supply-chain attacks.
+ */
+import { Chains, Network } from './types.js';
+import { TokenAddressMismatchError, UnknownTokenError, } from './errors.js';
+import { deepFreeze } from './deep-freeze.js';
+const lower = (s) => s.toLowerCase();
+/**
+ * The frozen registry. Entries here are the authoritative truth.
+ *
+ * Sources:
+ *   - USDC: Circle's canonical contract list (circle.com / developers.circle.com)
+ *   - USDT: Tether's published contracts (tether.to/transparency)
+ *   - DAI: MakerDAO's canonical deployments
+ *   - WETH: chain-native wrappers from each ecosystem's docs
+ */
+export const TOKEN_REGISTRY = deepFreeze({
+    [Chains.ETH]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'USD Coin',
+                decimals: 6,
+                address: lower('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'),
+            },
+            USDT: {
+                symbol: 'USDT',
+                name: 'Tether USD',
+                decimals: 6,
+                address: lower('0xdAC17F958D2ee523a2206206994597C13D831ec7'),
+            },
+            DAI: {
+                symbol: 'DAI',
+                name: 'Dai Stablecoin',
+                decimals: 18,
+                address: lower('0x6B175474E89094C44Da98b954EedeAC495271d0F'),
+            },
+            WETH: {
+                symbol: 'WETH',
+                name: 'Wrapped Ether',
+                decimals: 18,
+                address: lower('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'),
+            },
+        }),
+    },
+    [Chains.POLYGON]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'USD Coin',
+                decimals: 6,
+                address: lower('0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'),
+            },
+            USDT: {
+                symbol: 'USDT',
+                name: 'Tether USD',
+                decimals: 6,
+                address: lower('0xc2132D05D31c914a87C6611C10748AEb04B58e8F'),
+            },
+            DAI: {
+                symbol: 'DAI',
+                name: 'Dai Stablecoin',
+                decimals: 18,
+                address: lower('0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063'),
+            },
+            WETH: {
+                symbol: 'WETH',
+                name: 'Wrapped Ether',
+                decimals: 18,
+                address: lower('0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619'),
+            },
+        }),
+    },
+    [Chains.BINANCE]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'Binance-Peg USD Coin',
+                decimals: 18,
+                address: lower('0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d'),
+            },
+            USDT: {
+                symbol: 'USDT',
+                name: 'Binance-Peg Tether USD',
+                decimals: 18,
+                address: lower('0x55d398326f99059fF775485246999027B3197955'),
+            },
+            DAI: {
+                symbol: 'DAI',
+                name: 'Binance-Peg Dai',
+                decimals: 18,
+                address: lower('0x1AF3F329e8BE154074D8769D1FFa4eE058B1DBc3'),
+            },
+        }),
+    },
+    [Chains.BASE]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'USD Coin',
+                decimals: 6,
+                address: lower('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'),
+            },
+            WETH: {
+                symbol: 'WETH',
+                name: 'Wrapped Ether',
+                decimals: 18,
+                address: lower('0x4200000000000000000000000000000000000006'),
+            },
+        }),
+    },
+    [Chains.LINEA]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'USD Coin',
+                decimals: 6,
+                address: lower('0x176211869cA2b568f2A7D4EE941E073a821EE1ff'),
+            },
+            WETH: {
+                symbol: 'WETH',
+                name: 'Wrapped Ether',
+                decimals: 18,
+                address: lower('0xe5D7C2a44FfDDf6b295A15c148167daaAf5Cf34f'),
+            },
+        }),
+    },
+    [Chains.SKALE]: {
+        [Network.MAINNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'SKALE USD Coin',
+                decimals: 6,
+                address: lower('0x7Cf76E740Cb23b99337b21F392F22c47Ad910c67'),
+            },
+        }),
+        [Network.TESTNET]: Object.freeze({
+            USDC: {
+                symbol: 'USDC',
+                name: 'SKALE USD Coin (Testnet)',
+                decimals: 6,
+                address: lower('0x2aebcdc4f9F9149A50422FfF86198cB0939EA165'),
+            },
+        }),
+    },
+    [Chains.REDBELLY]: {},
+    [Chains.BITLAYER]: {},
+    [Chains.SOLANA]: {},
+    [Chains.XION]: {},
+    [Chains.UNSTOPPABLE]: {},
+});
+export function getTokenInfo(chain, network, symbol) {
+    const upperSymbol = symbol.toUpperCase();
+    const chainEntry = TOKEN_REGISTRY[chain];
+    const netEntry = chainEntry[network];
+    const token = netEntry?.[upperSymbol];
+    if (!token) {
+        throw new UnknownTokenError(chain, upperSymbol);
+    }
+    return token;
+}
+export function hasToken(chain, network, symbol) {
+    try {
+        getTokenInfo(chain, network, symbol);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function listTokens(chain, network) {
+    const chainEntry = TOKEN_REGISTRY[chain];
+    const netEntry = chainEntry[network];
+    return netEntry ? Object.freeze(Object.values(netEntry)) : [];
+}
+/**
+ * If `claimedAddress` is provided, assert it matches the canonical
+ * registry value for `symbol` on the given (chain, network). On match,
+ * returns the canonical `TokenInfo`. On mismatch — even of one nibble
+ * — throws `TokenAddressMismatchError`.
+ *
+ * If `claimedAddress` is omitted, returns the canonical entry.
+ *
+ * This is the primary call-site for blocking the "look-alike USDC
+ * drainer" class of attacks: a malicious backend cannot persuade the
+ * checkout to send funds to its address by claiming "this is USDC".
+ */
+export function assertCanonicalTokenAddress(args) {
+    const canonical = getTokenInfo(args.chain, args.network, args.symbol);
+    if (args.claimedAddress !== undefined) {
+        if (!/^0[xX][a-fA-F0-9]{40}$/u.test(args.claimedAddress)) {
+            throw new TokenAddressMismatchError(args.chain, args.symbol, canonical.address, args.claimedAddress);
+        }
+        const claimedLower = args.claimedAddress.toLowerCase();
+        if (claimedLower !== canonical.address) {
+            throw new TokenAddressMismatchError(args.chain, args.symbol, canonical.address, claimedLower);
+        }
+    }
+    return canonical;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/dist/tx-builder.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transaction-payload builders.
+ *
+ * These functions only construct well-formed `bigint`-typed call-data
+ * and EIP-712 typed-data structures. They do NOT broadcast anything
+ * and they do NOT touch a wallet — that is the responsibility of
+ * the `@droplinked_inc/wallet-connection` connector.
+ *
+ * Every input is validated through `chains.ts` / `tokens.ts` so an
+ * attacker cannot smuggle in a hostile chainId, token address, or
+ * amount via a query string or backend response.
+ */
+import { type Hex } from 'viem';
+import { Chains, Network, type EvmAddress } from './types.js';
+export interface Erc20TransferArgs {
+    chain: Chains;
+    network: Network;
+    /** Canonical symbol — "USDC", "USDT", … — looked up in the registry. */
+    tokenSymbol: string;
+    /** Optional caller-supplied address. If present, must match the registry. */
+    claimedTokenAddress?: string;
+    to: string;
+    amount: bigint | string | number;
+}
+export interface BuiltCall {
+    readonly to: EvmAddress;
+    readonly data: Hex;
+    readonly value: bigint;
+    readonly chainIdNumber: number;
+}
+/**
+ * Build an ERC-20 `transfer(address,uint256)` call. Returns the
+ * verified token-contract `to` address and ABI-encoded `data`.
+ */
+export declare function buildErc20Transfer(args: Erc20TransferArgs): BuiltCall;
+/**
+ * Build an ERC-20 `approve(spender,uint256)` call.
+ *
+ * Hardening note: a 0 amount IS allowed here, because the safe
+ * approve-twice pattern (`approve(spender, 0)` followed by
+ * `approve(spender, N)`) is the only way to defeat the front-run
+ * race on legacy USDT-like contracts.
+ */
+export declare function buildErc20Approve(args: {
+    chain: Chains;
+    network: Network;
+    tokenSymbol: string;
+    claimedTokenAddress?: string;
+    spender: string;
+    amount: bigint | string | number;
+}): BuiltCall;
+export interface Eip712Domain {
+    readonly name: string;
+    readonly version: string;
+    readonly chainId: number;
+    readonly verifyingContract: EvmAddress;
+}
+/**
+ * Build an EIP-712 domain object pinned to a specific chain from the
+ * registry. The caller cannot smuggle a bogus chainId — it is derived
+ * from the (chain, network) pair, not user input.
+ */
+export declare function buildEip712Domain(args: {
+    chain: Chains;
+    network: Network;
+    name: string;
+    version: string;
+    verifyingContract: string;
+}): Eip712Domain;
+export declare function buildNativeTransfer(args: {
+    chain: Chains;
+    network: Network;
+    to: string;
+    amount: bigint | string | number;
+}): BuiltCall;
+//# sourceMappingURL=tx-builder.d.ts.map

package/dist/tx-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx-builder.d.ts","sourceRoot":"","sources":["../src/tx-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAgC,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,UAAU,EAAmC,MAAM,YAAY,CAAC;AAO/F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CA6BrE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC,GAAG,SAAS,CAyBZ;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,YAAY,CAcf;AAID,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC,GAAG,SAAS,CAaZ"}

package/dist/tx-builder.js

@@ -0,0 +1,116 @@
+/**
+ * Transaction-payload builders.
+ *
+ * These functions only construct well-formed `bigint`-typed call-data
+ * and EIP-712 typed-data structures. They do NOT broadcast anything
+ * and they do NOT touch a wallet — that is the responsibility of
+ * the `@droplinked_inc/wallet-connection` connector.
+ *
+ * Every input is validated through `chains.ts` / `tokens.ts` so an
+ * attacker cannot smuggle in a hostile chainId, token address, or
+ * amount via a query string or backend response.
+ */
+import { encodeFunctionData, erc20Abi } from 'viem';
+import { EvmAddressSchema, Uint256Schema } from './types.js';
+import { getChainDetails } from './chains.js';
+import { assertCanonicalTokenAddress } from './tokens.js';
+import { InvalidParametersException } from './errors.js';
+/**
+ * Build an ERC-20 `transfer(address,uint256)` call. Returns the
+ * verified token-contract `to` address and ABI-encoded `data`.
+ */
+export function buildErc20Transfer(args) {
+    const details = getChainDetails(args.chain, args.network);
+    const token = assertCanonicalTokenAddress({
+        chain: args.chain,
+        network: args.network,
+        symbol: args.tokenSymbol,
+        ...(args.claimedTokenAddress !== undefined
+            ? { claimedAddress: args.claimedTokenAddress }
+            : {}),
+    });
+    const recipient = EvmAddressSchema.parse(args.to);
+    const amount = Uint256Schema.parse(args.amount);
+    if (amount === 0n) {
+        throw new InvalidParametersException(args.chain, 'transfer amount must be > 0');
+    }
+    const data = encodeFunctionData({
+        abi: erc20Abi,
+        functionName: 'transfer',
+        args: [recipient, amount],
+    });
+    return {
+        to: token.address,
+        data,
+        value: 0n,
+        chainIdNumber: details.chainIdNumber,
+    };
+}
+/**
+ * Build an ERC-20 `approve(spender,uint256)` call.
+ *
+ * Hardening note: a 0 amount IS allowed here, because the safe
+ * approve-twice pattern (`approve(spender, 0)` followed by
+ * `approve(spender, N)`) is the only way to defeat the front-run
+ * race on legacy USDT-like contracts.
+ */
+export function buildErc20Approve(args) {
+    const details = getChainDetails(args.chain, args.network);
+    const token = assertCanonicalTokenAddress({
+        chain: args.chain,
+        network: args.network,
+        symbol: args.tokenSymbol,
+        ...(args.claimedTokenAddress !== undefined
+            ? { claimedAddress: args.claimedTokenAddress }
+            : {}),
+    });
+    const spender = EvmAddressSchema.parse(args.spender);
+    const amount = Uint256Schema.parse(args.amount);
+    const data = encodeFunctionData({
+        abi: erc20Abi,
+        functionName: 'approve',
+        args: [spender, amount],
+    });
+    return {
+        to: token.address,
+        data,
+        value: 0n,
+        chainIdNumber: details.chainIdNumber,
+    };
+}
+/**
+ * Build an EIP-712 domain object pinned to a specific chain from the
+ * registry. The caller cannot smuggle a bogus chainId — it is derived
+ * from the (chain, network) pair, not user input.
+ */
+export function buildEip712Domain(args) {
+    if (args.name.length === 0 || args.name.length > 64) {
+        throw new InvalidParametersException(args.chain, 'domain name length 1..64');
+    }
+    if (args.version.length === 0 || args.version.length > 16) {
+        throw new InvalidParametersException(args.chain, 'domain version length 1..16');
+    }
+    const details = getChainDetails(args.chain, args.network);
+    return {
+        name: args.name,
+        version: args.version,
+        chainId: details.chainIdNumber,
+        verifyingContract: EvmAddressSchema.parse(args.verifyingContract),
+    };
+}
+/* ------------------------- native-coin transfer --------------------------- */
+export function buildNativeTransfer(args) {
+    const details = getChainDetails(args.chain, args.network);
+    const to = EvmAddressSchema.parse(args.to);
+    const amount = Uint256Schema.parse(args.amount);
+    if (amount === 0n) {
+        throw new InvalidParametersException(args.chain, 'transfer amount must be > 0');
+    }
+    return {
+        to,
+        data: '0x',
+        value: amount,
+        chainIdNumber: details.chainIdNumber,
+    };
+}
+//# sourceMappingURL=tx-builder.js.map

package/dist/tx-builder.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Public types and zod schemas for @droplinked_inc/web3-kit.
+ *
+ * Every value crossing an external boundary (user-supplied chain id,
+ * token symbol, RPC URL, ABI-encoded payload) is validated against these
+ * schemas. See THREAT_MODEL.md for the rationale on each invariant.
+ */
+import { z } from 'zod';
+/**
+ * Canonical chain identifier used across the kit. String-valued so the
+ * representation is stable across JSON wire-formats and survives
+ * postMessage / fetch round-trips.
+ */
+export declare enum Chains {
+    POLYGON = "POLYGON",
+    BINANCE = "BINANCE",
+    SKALE = "SKALE",
+    BASE = "BASE",
+    LINEA = "LINEA",
+    ETH = "ETH",
+    SOLANA = "SOLANA",
+    REDBELLY = "REDBELLY",
+    UNSTOPPABLE = "UNSTOPPABLE",
+    BITLAYER = "BITLAYER",
+    XION = "XION"
+}
+export declare enum Network {
+    TESTNET = "TESTNET",
+    MAINNET = "MAINNET"
+}
+export declare enum Groups {
+    EVM = "EVM",
+    SOL = "SOL",
+    BTC = "BTC",
+    XION = "XION",
+    UD = "UD"
+}
+export declare const ChainsSchema: z.ZodNativeEnum<typeof Chains>;
+export declare const NetworkSchema: z.ZodNativeEnum<typeof Network>;
+export declare const GroupsSchema: z.ZodNativeEnum<typeof Groups>;
+export declare const EvmAddressSchema: z.ZodEffects<z.ZodString, `0x${string}`, string>;
+export type EvmAddress = `0x${string}`;
+export declare const HexStringSchema: z.ZodString;
+/**
+ * Accepts the v1.0.13 wire-format for unsigned 256-bit numbers
+ * (`bigint`, base-10 string, non-negative finite integer) and
+ * normalizes to bigint. Negative, fractional, or out-of-range
+ * inputs are rejected.
+ */
+export declare const Uint256Schema: z.ZodEffects<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber, z.ZodString]>, bigint, string | number | bigint>, bigint, string | number | bigint>;
+export type Uint256 = bigint;
+/**
+ * Canonical short-symbol identifier for known fiat-equivalent or
+ * native tokens used during checkout. The set is intentionally small
+ * — anything outside is rejected by the registry to prevent symbol
+ * impersonation attacks (see THREAT_MODEL.md §4).
+ */
+export declare enum PaymentTokens {
+    ETH = "ETH",
+    BNB = "BNB",
+    MATIC = "MATIC",
+    SOL = "SOL",
+    BTC = "BTC",
+    USDC = "USDC",
+    USDT = "USDT",
+    USDS = "USDS",
+    DAI = "DAI",
+    WETH = "WETH"
+}
+export declare const PaymentTokensSchema: z.ZodNativeEnum<typeof PaymentTokens>;
+export declare const ChainPaymentSchema: z.ZodObject<{
+    totalPrice: z.ZodEffects<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber, z.ZodString]>, bigint, string | number | bigint>, bigint, string | number | bigint>;
+    tbdValues: z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber, z.ZodString]>, bigint, string | number | bigint>, bigint, string | number | bigint>, "many">;
+    tbdReceivers: z.ZodArray<z.ZodEffects<z.ZodString, `0x${string}`, string>, "many">;
+    tokenAddress: z.ZodOptional<z.ZodEffects<z.ZodString, `0x${string}`, string>>;
+    memo: z.ZodString;
+    chainLinkRoundId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    totalPrice: bigint;
+    tbdValues: bigint[];
+    tbdReceivers: `0x${string}`[];
+    memo: string;
+    tokenAddress?: `0x${string}` | undefined;
+    chainLinkRoundId?: string | undefined;
+}, {
+    totalPrice: string | number | bigint;
+    tbdValues: (string | number | bigint)[];
+    tbdReceivers: string[];
+    memo: string;
+    tokenAddress?: string | undefined;
+    chainLinkRoundId?: string | undefined;
+}>;
+export type IChainPayment = z.infer<typeof ChainPaymentSchema>;
+export declare const PurchaseConfirmationDataSchema: z.ZodArray<z.ZodObject<{
+    amount: z.ZodNumber;
+    productId: z.ZodString;
+    nullifier: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    amount: number;
+    productId: string;
+    nullifier: string;
+}, {
+    amount: number;
+    productId: string;
+    nullifier: string;
+}>, "many">;
+export declare const PurchaseSignatureSchema: z.ZodObject<{
+    signature: z.ZodString;
+    purchaseData: z.ZodArray<z.ZodObject<{
+        amount: z.ZodNumber;
+        productId: z.ZodString;
+        nullifier: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: number;
+        productId: string;
+        nullifier: string;
+    }, {
+        amount: number;
+        productId: string;
+        nullifier: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    purchaseData: {
+        amount: number;
+        productId: string;
+        nullifier: string;
+    }[];
+}, {
+    signature: string;
+    purchaseData: {
+        amount: number;
+        productId: string;
+        nullifier: string;
+    }[];
+}>;
+export type PurchaseSignature = z.infer<typeof PurchaseSignatureSchema>;
+export declare const ZERO_ADDRESS: EvmAddress;
+export declare enum NFTType {
+    ERC1155 = 0,
+    ERC721 = 1
+}
+export declare enum ProductType {
+    DIGITAL = 0,
+    POD = 1,
+    PHYSICAL = 2
+}
+export declare enum Actions {
+    Payment = "Payment",
+    ClaimNFT = "ClaimNFT",
+    Record = "Record",
+    Auth = "Auth",
+    Login = "Login"
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;GAIG;AACH,oBAAY,MAAM;IAChB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,WAAW,gBAAgB;IAC3B,QAAQ,aAAa;IACrB,IAAI,SAAS;CACd;AAED,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED,oBAAY,MAAM;IAChB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,EAAE,OAAO;CACV;AAED,eAAO,MAAM,YAAY,gCAAuB,CAAC;AACjD,eAAO,MAAM,aAAa,iCAAwB,CAAC;AACnD,eAAO,MAAM,YAAY,gCAAuB,CAAC;AAMjD,eAAO,MAAM,gBAAgB,kDAGwB,CAAC;AAEtD,MAAM,MAAM,UAAU,GAAG,KAAK,MAAM,EAAE,CAAC;AAEvC,eAAO,MAAM,eAAe,aAEuB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,qJAOiD,CAAC;AAE5E,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAM7B;;;;;GAKG;AACH,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,mBAAmB,uCAA8B,CAAC;AAM/D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAO7B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAM/D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;WAM1C,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE,eAAO,MAAM,YAAY,EAAE,UAAyD,CAAC;AAErF,oBAAY,OAAO;IACjB,OAAO,IAAI;IACX,MAAM,IAAI;CACX;AAED,oBAAY,WAAW;IACrB,OAAO,IAAI;IACX,GAAG,IAAI;IACP,QAAQ,IAAI;CACb;AAED,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,KAAK,UAAU;CAChB"}