crypto-stable-pay 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# crypto-stable-pay
+
+Accept USDC/USDT (or any ERC-20) on multiple EVM networks using user wallets (MetaMask, Trust Wallet browser, Binance Web3 wallet, etc.).
+
+## Install
+npm i crypto-stable-pay ethers
+
+## Basic usage (transfer)
+```ts
+import { connectWallet, payWithErc20, waitForReceipt } from "crypto-stable-pay";
+
+const eip1193 = window.ethereum; // injected by wallet
+
+const from = await connectWallet(eip1193);
+
+const result = await payWithErc20(eip1193, {
+  chainId: 137, // Polygon
+  token: {
+    symbol: "USDC",
+    address: "0x...", // USDC contract on Polygon (you provide)
+    decimals: 6
+  },
+  recipient: "0xYourMerchantWallet",
+  amount: "12.50",
+  reference: "order_123"
+});
+
+const receipt = await waitForReceipt(eip1193, result.txHash, 1);
+console.log({ result, receipt });

package/dist/erc20.d.ts

@@ -0,0 +1,6 @@
+import { Contract, BrowserProvider } from "ethers";
+import type { Address, Eip1193Provider } from "./types";
+export declare const ERC20_ABI: readonly ["function decimals() view returns (uint8)", "function symbol() view returns (string)", "function allowance(address owner, address spender) view returns (uint256)", "function approve(address spender, uint256 value) returns (bool)", "function transfer(address to, uint256 value) returns (bool)", "function transferFrom(address from, address to, uint256 value) returns (bool)"];
+export declare function getBrowserProvider(eip1193: Eip1193Provider): BrowserProvider;
+export declare function getErc20(tokenAddress: Address, provider: BrowserProvider): Contract;
+export declare function toAtomic(amountHuman: string, decimals: number): Promise<bigint>;

package/dist/erc20.js

@@ -0,0 +1,18 @@
+import { Contract, BrowserProvider, ethers } from "ethers";
+export const ERC20_ABI = [
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "function approve(address spender, uint256 value) returns (bool)",
+    "function transfer(address to, uint256 value) returns (bool)",
+    "function transferFrom(address from, address to, uint256 value) returns (bool)"
+];
+export function getBrowserProvider(eip1193) {
+    return new BrowserProvider(eip1193);
+}
+export function getErc20(tokenAddress, provider) {
+    return new Contract(tokenAddress, ERC20_ABI, provider);
+}
+export async function toAtomic(amountHuman, decimals) {
+    return ethers.parseUnits(amountHuman, decimals);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./networks";
+export * from "./pay";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./networks";
+export * from "./pay";

package/dist/networks.d.ts

@@ -0,0 +1,2 @@
+import type { NetworkSpec } from "./types";
+export declare const NETWORKS: Record<number, NetworkSpec>;

package/dist/networks.js

@@ -0,0 +1,10 @@
+// You can ship a few common ones, but do NOT hardcode token addresses here.
+// Site owners pass USDC/USDT contract addresses per chain.
+export const NETWORKS = {
+    1: { chainId: 1, name: "Ethereum Mainnet" },
+    56: { chainId: 56, name: "BNB Smart Chain" },
+    137: { chainId: 137, name: "Polygon" },
+    42161: { chainId: 42161, name: "Arbitrum One" },
+    10: { chainId: 10, name: "Optimism" },
+    8453: { chainId: 8453, name: "Base" }
+};

package/dist/pay.d.ts

@@ -0,0 +1,17 @@
+import type { Address, Eip1193Provider, PaymentReceipt, PaymentRequest, PaymentResult } from "./types";
+export declare function connectWallet(eip1193: Eip1193Provider): Promise<Address>;
+export declare function getChainId(eip1193: Eip1193Provider): Promise<number>;
+export declare function switchChain(eip1193: Eip1193Provider, chainId: number): Promise<void>;
+export declare function addChain(eip1193: Eip1193Provider, chain: {
+    chainId: number;
+    chainName: string;
+    rpcUrls: string[];
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    blockExplorerUrls?: string[];
+}): Promise<void>;
+export declare function payWithErc20(eip1193: Eip1193Provider, req: PaymentRequest): Promise<PaymentResult>;
+export declare function waitForReceipt(eip1193: Eip1193Provider, txHash: string, confirmations?: number): Promise<PaymentReceipt>;

package/dist/pay.js

@@ -0,0 +1,93 @@
+import { getBrowserProvider, getErc20, toAtomic } from "./erc20";
+function asAddress(v) {
+    if (typeof v !== "string" || !v.startsWith("0x"))
+        throw new Error("Invalid address");
+    return v;
+}
+export async function connectWallet(eip1193) {
+    const accounts = (await eip1193.request({ method: "eth_requestAccounts" }));
+    if (!accounts?.length)
+        throw new Error("No accounts returned");
+    return asAddress(accounts[0]);
+}
+export async function getChainId(eip1193) {
+    const hex = (await eip1193.request({ method: "eth_chainId" }));
+    return Number.parseInt(hex, 16);
+}
+export async function switchChain(eip1193, chainId) {
+    const hexChainId = "0x" + chainId.toString(16);
+    await eip1193.request({
+        method: "wallet_switchEthereumChain",
+        params: [{ chainId: hexChainId }]
+    });
+}
+// Optional: only needed if you want to support adding unknown chains automatically.
+export async function addChain(eip1193, chain) {
+    const hexChainId = "0x" + chain.chainId.toString(16);
+    await eip1193.request({
+        method: "wallet_addEthereumChain",
+        params: [{
+                chainId: hexChainId,
+                chainName: chain.chainName,
+                rpcUrls: chain.rpcUrls,
+                nativeCurrency: chain.nativeCurrency,
+                blockExplorerUrls: chain.blockExplorerUrls ?? []
+            }]
+    });
+}
+export async function payWithErc20(eip1193, req) {
+    const provider = getBrowserProvider(eip1193);
+    const signer = await provider.getSigner();
+    const from = asAddress(await signer.getAddress());
+    const currentChain = await getChainId(eip1193);
+    if (currentChain !== req.chainId) {
+        // you can choose to auto-switch or throw
+        await switchChain(eip1193, req.chainId);
+    }
+    const amountAtomic = await toAtomic(req.amount, req.token.decimals);
+    const base = getErc20(req.token.address, provider).connect(signer);
+    const erc20 = base;
+    if (req.requireApproval) {
+        if (!req.spender)
+            throw new Error("spender is required when requireApproval=true");
+        const allowance = await erc20.allowance(from, req.spender);
+        if (allowance < amountAtomic) {
+            const approveTx = await erc20.approve(req.spender, amountAtomic);
+            await approveTx.wait(1);
+        }
+        const tx = await erc20.transferFrom(from, req.recipient, amountAtomic);
+        return {
+            txHash: tx.hash,
+            chainId: req.chainId,
+            from,
+            toToken: req.token.address,
+            recipient: req.recipient,
+            amountAtomic,
+            reference: req.reference
+        };
+    }
+    else {
+        const tx = await erc20.transfer(req.recipient, amountAtomic);
+        return {
+            txHash: tx.hash,
+            chainId: req.chainId,
+            from,
+            toToken: req.token.address,
+            recipient: req.recipient,
+            amountAtomic,
+            reference: req.reference
+        };
+    }
+}
+export async function waitForReceipt(eip1193, txHash, confirmations = 1) {
+    const provider = getBrowserProvider(eip1193);
+    const receipt = await provider.waitForTransaction(txHash, confirmations);
+    if (!receipt)
+        throw new Error("No receipt");
+    return {
+        status: receipt.status === 1 ? "confirmed" : "failed",
+        confirmations,
+        blockNumber: receipt.blockNumber,
+        txHash
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type Address = `0x${string}`;
+export type Eip1193Provider = {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+};
+export type TokenSpec = {
+    symbol: "USDC" | "USDT" | string;
+    address: Address;
+    decimals: number;
+};
+export type NetworkSpec = {
+    chainId: number;
+    name: string;
+    rpcUrls?: string[];
+    nativeCurrency?: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    blockExplorerUrls?: string[];
+};
+export type PaymentRequest = {
+    chainId: number;
+    token: TokenSpec;
+    recipient: Address;
+    amount: string;
+    reference?: string;
+    requireApproval?: boolean;
+    spender?: Address;
+};
+export type PaymentResult = {
+    txHash: string;
+    chainId: number;
+    from: Address;
+    toToken: Address;
+    recipient: Address;
+    amountAtomic: bigint;
+    reference?: string;
+};
+export type PaymentReceipt = {
+    status: "confirmed" | "failed";
+    confirmations: number;
+    blockNumber: number;
+    txHash: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "crypto-stable-pay",
+  "version": "0.1.0",
+  "description": "Accept USDC/USDT payments on multiple EVM networks via user wallets (MetaMask, Trust, Binance, ...)",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "usdc",
+    "usdt",
+    "payments",
+    "web3",
+    "erc20",
+    "metamask",
+    "evm"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ethers": "^6.16.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  }
+}