Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// x402-pay-core.js — browser-native wallet payment core for the three.ws paywall.
//
// The full-page paywall (paywall.html / paywall.js) lists wallet buttons but
// historically dead-ended on click. This module performs the real x402 payment
// flow, driving each wallet button from connect → sign → settle → unlock with
// no fake progress. It mirrors the proven flow already shipped in the drop-in
// modal (public/x402.js): Solana wallets sign a server-prepared SPL transfer
// (via /api/x402-checkout), EVM wallets sign EIP-3009 transferWithAuthorization
// typed data locally. The signed payload is base64-encoded into the X-PAYMENT
// header, the original gated resource is retried, and the unlocked content +
// settlement receipt are returned to the caller.
//
// Loaded as a native ES module (`<script type="module">`); it attaches
// `window.PaywallWallet` for the classic paywall.js controller, and exports its
// pure helpers as named exports so the payment-building logic is unit-testable
// without a browser or a wallet.
// ──────────────────────────────────────────────────────── network helpers ────
// USDC EIP-3009 typed-data domains, keyed by CAIP-2 network id. `version` must
// match the deployed USDC implementation's EIP712 domain version — Base USDC is
// at "2"; signing with the wrong version yields a domain hash the facilitator
// rejects.
export const EVM_NETWORKS = {
'eip155:8453': { chainId: 8453, name: 'Base', explorer: 'https://basescan.org/tx/' },
'eip155:84532': {
chainId: 84532,
name: 'Base Sepolia',
explorer: 'https://sepolia.basescan.org/tx/',
},
'eip155:42161': { chainId: 42161, name: 'Arbitrum', explorer: 'https://arbiscan.io/tx/' },
'eip155:10': { chainId: 10, name: 'Optimism', explorer: 'https://optimistic.etherscan.io/tx/' },
};
export function isSolanaNetwork(net) {
return typeof net === 'string' && (net === 'solana' || net.startsWith('solana:'));
}
export function isEvmNetwork(net) {
return typeof net === 'string' && net.startsWith('eip155:');
}
// The paywall only signs EIP-3009 transferWithAuthorization for EVM. When the
// server publishes both an EIP-3009 entry and a Permit2 sibling (the
// gas-sponsoring path used by SDK clients), pick the EIP-3009 one — signing
// typed-data against the Permit2 entry builds a payload the facilitator rejects.
export function isEip3009Accept(accept) {
if (!isEvmNetwork(accept?.network)) return false;
const m = accept?.extra?.assetTransferMethod;
return !m || m === 'eip3009';
}
export function explorerUrl(network, tx) {
if (!tx) return null;
if (isSolanaNetwork(network)) return `https://solscan.io/tx/${tx}`;
const meta = EVM_NETWORKS[network];
return meta ? `${meta.explorer}${tx}` : null;
}
// The x402 spec's canonical atomic-price field is `maxAmountRequired`; our
// server (and many merchants) emit `amount`. We read `amount` everywhere
// downstream, so coerce once at ingestion.
export function normalizeAccept(accept) {
if (!accept || typeof accept !== 'object') return accept;
const amount = accept.amount ?? accept.maxAmountRequired;
return amount != null && accept.amount == null ? { ...accept, amount: String(amount) } : accept;
}
// Resolve the absolute URL of the gated resource to retry after payment. Each
// 402 `accept` entry carries the resource URL server-side; fall back to the
// paywall's `?return=` URL (made absolute) when it doesn't.
export function resolveResourceUrl(accept, fallbackUrl, origin) {
const base = origin || (typeof location !== 'undefined' ? location.origin : 'https://three.ws');
const candidate = accept?.resource || fallbackUrl || '/';
try {
return new URL(candidate, base).href;
} catch {
return new URL('/', base).href;
}
}
// ─────────────────────────────────────────────────────────── encoding ────────
export function b64encode(obj) {
const json = JSON.stringify(obj);
if (typeof Buffer !== 'undefined') return Buffer.from(json, 'utf8').toString('base64');
return btoa(unescape(encodeURIComponent(json)));
}
export function b64decode(str) {
if (!str) return null;
try {
const bin =
typeof Buffer !== 'undefined'
? Buffer.from(str, 'base64').toString('utf8')
: decodeURIComponent(escape(atob(str)));
return JSON.parse(bin);
} catch {
return null;
}
}
export function base64ToUint8Array(b64) {
if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(b64, 'base64'));
const bin = atob(b64);
const arr = new Uint8Array(bin.length);
for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
return arr;
}
export function uint8ArrayToBase64(arr) {
if (typeof Buffer !== 'undefined') return Buffer.from(arr).toString('base64');
let bin = '';
for (let i = 0; i < arr.length; i++) bin += String.fromCharCode(arr[i]);
return btoa(bin);
}
export function randomHex(bytes) {
const arr = new Uint8Array(bytes);
(globalThis.crypto || crypto).getRandomValues(arr);
return Array.from(arr)
.map((b) => b.toString(16).padStart(2, '0'))
.join('');
}
export function friendlyError(err) {
const msg = err?.shortMessage || err?.message || String(err);
if (/user rejected|user denied|reject|cancell?ed/i.test(msg)) return 'Cancelled in wallet';
return msg.slice(0, 240);
}
// ───────────────────────────────────────────── pre-flight balance guard ───────
//
// The balance check is a UX guard, NOT a security gate: it spares the buyer from
// signing a transaction that can only fail at settle with an opaque error, and
// lets the UI offer "add funds" instead. It is deliberately fail-open — when the
// balance can't be read (flaky RPC, provider quirk) it returns null and the
// payment proceeds exactly as before. Only a POSITIVE shortfall blocks signing.
// Render an atomic token amount as a trimmed decimal string (BigInt-safe — token
// amounts can exceed Number's safe integer range).
export function formatTokenAmount(atomic, decimals = 6) {
const neg = BigInt(atomic) < 0n;
const abs = neg ? -BigInt(atomic) : BigInt(atomic);
const base = 10n ** BigInt(decimals);
const whole = abs / base;
const frac = (abs % base).toString().padStart(decimals, '0').replace(/0+$/, '');
return `${neg ? '-' : ''}${whole}${frac ? `.${frac}` : ''}`;
}
// Structured insufficient-funds error so the UI can render an actionable state
// (required / current / shortfall + an add-funds CTA) instead of a raw string.
export function insufficientFundsError({ required, balance, accept }) {
const decimals = Number(accept?.extra?.decimals ?? 6);
const symbol = accept?.extra?.name || 'USDC';
const req = BigInt(required);
const bal = BigInt(balance);
const shortfall = req > bal ? req - bal : 0n;
const err = new Error(
`Not enough ${symbol} — you need ${formatTokenAmount(req, decimals)} ${symbol} but your wallet holds ${formatTokenAmount(bal, decimals)} ${symbol}.`,
);
err.code = 'insufficient_funds';
err.insufficient = {
symbol,
decimals,
network: accept?.network || null,
asset: accept?.asset || null,
required: req.toString(),
requiredFormatted: formatTokenAmount(req, decimals),
balance: bal.toString(),
balanceFormatted: formatTokenAmount(bal, decimals),
shortfall: shortfall.toString(),
shortfallFormatted: formatTokenAmount(shortfall, decimals),
};
return err;
}
// RPC endpoint for the Solana balance read. Overridable via meta tag / global so
// a deployment can point at its own (Helius) RPC instead of the rate-limited
// public one; mirrors the WalletConnect project-id resolution.
function solanaRpcUrl() {
if (typeof document !== 'undefined') {
const meta = document.querySelector('meta[name="solana-rpc-url"]');
if (meta?.content) return meta.content;
}
if (typeof window !== 'undefined' && window.SOLANA_RPC_URL) return window.SOLANA_RPC_URL;
// Last resort: the /api/solana-rpc proxy co-deployed with this script, which
// fails over across Helius → Alchemy → dRPC → five keyless public lanes, so the
// balance read survives any single provider (an expired Helius plan included)
// being down. Resolved from this module's own serving origin, NOT a hardcoded
// host: as a third-party embed the script is loaded from three.ws (resolves to
// three.ws); as the first-party app on a preview/dev/tunnel origin it resolves
// same-origin, so the read never trips that origin's CORS allowlist.
return scriptOrigin() + '/api/solana-rpc';
}
// Origin that served this module — where its same-deployment /api proxy lives.
function scriptOrigin() {
try {
const o = new URL(import.meta.url).origin;
if (o && o !== 'null') return o;
} catch {}
if (typeof location !== 'undefined' && location.origin && location.origin !== 'null') {
return location.origin;
}
return 'https://three.ws';
}
// Sum the owner's SPL balance for `mint`. Returns a BigInt of atomic units, or
// null when the read fails (→ caller proceeds without blocking).
export async function readSolanaTokenBalance({ owner, mint, rpcUrl }) {
try {
const res = await fetch(rpcUrl || solanaRpcUrl(), {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'getTokenAccountsByOwner',
params: [owner, { mint }, { encoding: 'jsonParsed' }],
}),
});
if (!res.ok) return null;
const data = await res.json();
const accounts = data?.result?.value || [];
let total = 0n;
for (const acc of accounts) {
const amt = acc?.account?.data?.parsed?.info?.tokenAmount?.amount;
if (amt != null) total += BigInt(amt);
}
return total;
} catch {
return null;
}
}
// ERC-20 balanceOf(owner) calldata: selector 0x70a08231 + 32-byte left-padded owner.
export function erc20BalanceOfCalldata(owner) {
return '0x70a08231' + String(owner).toLowerCase().replace(/^0x/, '').padStart(64, '0');
}
// Read an ERC-20 balance via the connected wallet provider (it IS the RPC for the
// current chain — no external endpoint needed). Returns a BigInt, or null on failure.
export async function readEvmTokenBalance({ provider, token, owner }) {
try {
const hex = await provider.request({
method: 'eth_call',
params: [{ to: token, data: erc20BalanceOfCalldata(owner) }, 'latest'],
});
if (!hex || hex === '0x') return null;
return BigInt(hex);
} catch {
return null;
}
}
// Throw insufficientFundsError ONLY when a balance was positively read and falls
// short of accept.amount. A null read (inconclusive) never blocks the payment.
export async function assertSufficientBalance({ accept, owner, provider, rpcUrl }) {
const required = BigInt(accept.amount);
let balance = null;
if (isSolanaNetwork(accept.network)) {
balance = await readSolanaTokenBalance({ owner, mint: accept.asset, rpcUrl });
} else if (isEvmNetwork(accept.network) && provider) {
balance = await readEvmTokenBalance({ provider, token: accept.asset, owner });
}
if (balance !== null && balance < required) {
throw insufficientFundsError({ required, balance, accept });
}
return balance;
}
// ──────────────────────────────────────────── payment payload builders ────────
// Body for POST /api/x402-checkout?action=prepare. The server returns a
// partially-signed v0 SPL transfer for the buyer's wallet to co-sign.
export function buildPrepareBody(accept, buyer) {
return { accept: normalizeAccept(accept), buyer };
}
// EIP-3009 transferWithAuthorization typed data for an EVM USDC payment.
// `nowSeconds` is injectable so the build is deterministic under test.
export function buildEip3009TypedData({ accept, payerAddress, chainId, nowSeconds, nonce }) {
const now = nowSeconds != null ? nowSeconds : Math.floor(Date.now() / 1000);
const validAfter = 0;
const validBefore = now + (accept.maxTimeoutSeconds || 600);
const authNonce = nonce || '0x' + randomHex(32);
const domain = {
name: accept.extra?.name || 'USD Coin',
version: accept.extra?.version || '2',
chainId,
verifyingContract: accept.asset,
};
const types = {
EIP712Domain: [
{ name: 'name', type: 'string' },
{ name: 'version', type: 'string' },
{ name: 'chainId', type: 'uint256' },
{ name: 'verifyingContract', type: 'address' },
],
TransferWithAuthorization: [
{ name: 'from', type: 'address' },
{ name: 'to', type: 'address' },
{ name: 'value', type: 'uint256' },
{ name: 'validAfter', type: 'uint256' },
{ name: 'validBefore', type: 'uint256' },
{ name: 'nonce', type: 'bytes32' },
],
};
const message = {
from: payerAddress,
to: accept.payTo,
value: accept.amount,
validAfter,
validBefore,
nonce: authNonce,
};
return {
typedData: { primaryType: 'TransferWithAuthorization', types, domain, message },
authorization: {
from: payerAddress,
to: accept.payTo,
value: accept.amount,
// CDP facilitator /verify requires the EIP-3009 time bounds as decimal
// strings, not JSON numbers — a numeric validAfter/validBefore is
// rejected with "'paymentPayload' is invalid". The signature is
// unaffected: uint256 0 and "0" encode to the same 32 bytes.
validAfter: String(validAfter),
validBefore: String(validBefore),
nonce: authNonce,
},
};
}
// Assemble the x402 PaymentPayload for an EVM EIP-3009 signature.
export function buildEvmPaymentPayload({ accept, signature, authorization, resourceUrl }) {
return {
x402Version: 2,
scheme: 'exact',
network: accept.network,
resource: { url: resourceUrl, mimeType: 'application/json' },
accepted: accept,
payload: { signature, authorization },
};
}
// ──────────────────────────────────────────────────── runtime dependencies ────
let _solanaWeb3 = null;
async function loadSolanaWeb3() {
if (_solanaWeb3) return _solanaWeb3;
// Dynamic import keeps the paywall tiny: web3.js is only fetched when a
// Solana payment is actually attempted. The shared loader tries esm.sh, then
// jsdelivr and unpkg for the same version, each under a deadline, and throws
// a typed error naming the hosts when all three are blocked.
const { loadModule } = await import('./load-module.js');
try {
_solanaWeb3 = await loadModule('https://esm.sh/@solana/[email protected]?bundle');
} catch (err) {
if (err?.code === 'module_unavailable') {
throw new Error(
'The Solana wallet component could not be loaded (' + err.hosts.join(', ') + ' unreachable or blocked by this page\'s security policy). Pay with a Base wallet instead; that path needs no third-party code.',
);
}
throw err;
}
return _solanaWeb3;
}
async function postJson(url, body) {
const res = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
});
const text = await res.text();
let data;
try {
data = JSON.parse(text);
} catch {
data = { error: 'parse_error', error_description: text.slice(0, 200) };
}
if (!res.ok) {
const err = new Error(data.error_description || data.error || `HTTP ${res.status}`);
err.status = res.status;
err.data = data;
throw err;
}
return data;
}
// ───────────────────────────────────────────────────── provider detection ────
export function getSolanaProvider(walletName) {
if (typeof window === 'undefined') return null;
if (walletName === 'solflare') {
// Solflare injects window.solflare; some builds also flag window.solana.
if (window.solflare?.isSolflare || window.solflare) return window.solflare;
if (window.solana?.isSolflare) return window.solana;
return null;
}
// Phantom (default Solana wallet).
if (window.phantom?.solana) return window.phantom.solana;
if (window.solana?.isPhantom) return window.solana;
return window.solana || null;
}
// Pick the injected EVM provider matching the requested wallet. EIP-6963 / legacy
// multi-provider environments expose siblings under window.ethereum.providers.
export function getEvmProvider(walletName) {
if (typeof window === 'undefined') return null;
const eth = window.ethereum;
if (!eth) return null;
const list = Array.isArray(eth.providers) && eth.providers.length ? eth.providers : [eth];
const pick = (pred) => list.find(pred);
if (walletName === 'coinbase') {
return (
pick((p) => p.isCoinbaseWallet) ||
window.coinbaseWalletExtension ||
(eth.isCoinbaseWallet ? eth : null)
);
}
if (walletName === 'metamask') {
return pick((p) => p.isMetaMask && !p.isCoinbaseWallet) || (eth.isMetaMask ? eth : null);
}
// Generic injected fallback.
return eth;
}
const WALLET_LABELS = {
phantom: 'Phantom',
solflare: 'Solflare',
metamask: 'MetaMask',
coinbase: 'Coinbase Wallet',
walletconnect: 'WalletConnect',
};
function walletNotFound(walletName) {
const label = WALLET_LABELS[walletName] || 'Wallet';
const err = new Error(
`${label} not detected. Install the ${label} extension, then reload this page.`,
);
err.code = 'wallet_not_found';
return err;
}
// ──────────────────────────────────────────────────────────────── mobile ──────
// Mobile browsers have no injected wallet extension — the wallet app instead
// reopens the page inside its own in-app browser (where the provider IS
// injected) via a universal link. Detect the mobile case so we deep-link the
// user into their wallet instead of telling them to "install the extension",
// which is meaningless on a phone. `ua` is injectable so this is unit-testable.
export function isMobileBrowser(ua) {
const s = ua != null ? ua : typeof navigator !== 'undefined' ? navigator.userAgent || '' : '';
return /Android|iPhone|iPad|iPod|Mobile|Silk|Kindle|BlackBerry|Opera Mini|IEMobile/i.test(s);
}
// Universal/deep link that reopens `targetUrl` inside the wallet's in-app
// browser. The paywall passes its own page URL so the gated request (carried in
// `?req=`/`?return=`) is preserved and payment completes after the redirect.
export function walletDeeplink(walletName, targetUrl, ref) {
if (!targetUrl) return null;
const enc = encodeURIComponent(targetUrl);
const refQ = ref ? `?ref=${encodeURIComponent(ref)}` : '';
switch (walletName) {
case 'phantom':
return `https://phantom.app/ul/browse/${enc}${refQ}`;
case 'solflare':
return `https://solflare.com/ul/v1/browse/${enc}${refQ}`;
case 'coinbase':
return `https://go.cb-w.com/dapp?cb_url=${enc}`;
case 'metamask':
try {
const u = new URL(targetUrl);
return `https://metamask.app.link/dapp/${u.host}${u.pathname}${u.search}`;
} catch {
return `https://metamask.app.link/dapp/${enc}`;
}
default:
return null; // WalletConnect already handles mobile via its own modal.
}
}
// On mobile with no injected provider, navigate to the wallet's in-app browser.
// Returns true if a redirect was initiated (the caller should then stop, since
// the page is unloading). Side-effecting + window-guarded; the pure pieces above
// are what tests exercise.
function initiateMobileRedirect(walletName, label, onStatus) {
if (typeof window === 'undefined' || !isMobileBrowser()) return false;
const link = walletDeeplink(walletName, window.location.href, window.location.origin);
if (!link) return false;
onStatus?.('connecting', `Opening ${label}…`);
window.location.href = link;
return true;
}
// Thrown after a mobile redirect is initiated so the controller can distinguish
// "navigating to the wallet app" from a real failure and suppress the error UI.
function mobileRedirectError() {
const err = new Error('Opening your wallet app…');
err.code = 'mobile_redirect';
return err;
}
// ─────────────────────────────────────────────────────── settle + retry ──────
// Retry the gated resource with the X-PAYMENT proof and return the unlocked
// content plus the decoded settlement receipt.
//
// `request` lets a caller replay a resource that is not a plain GET. A paid
// POST route (the Endpoint Shopper takes its task and budget in a JSON body)
// answers a bodyless GET with a 405, so the buyer would settle on-chain and
// then get nothing back. Callers pass { method, body, headers } to replay the
// exact request that earned the 402. Default stays GET for the paywall page.
async function executePaid({ xPayment, resourceUrl, onStatus, accept, payerAddress, request }) {
onStatus?.('confirming', 'Unlocking content…');
const method = String(request?.method || 'GET').toUpperCase();
const init = {
method,
headers: { 'X-PAYMENT': xPayment, Accept: '*/*', ...(request?.headers || {}) },
};
if (request?.body != null && method !== 'GET' && method !== 'HEAD') init.body = request.body;
const res = await fetch(resourceUrl, init);
const ct = res.headers.get('content-type') || '';
const text = await res.text();
let result;
if (ct.includes('json')) {
try {
result = JSON.parse(text);
} catch {
result = text;
}
} else {
result = text;
}
if (!res.ok) {
const msg =
(result && typeof result === 'object' && (result.error_description || result.error)) ||
`HTTP ${res.status}`;
throw new Error(msg);
}
const payment = b64decode(res.headers.get('x-payment-response')) || {};
onStatus?.('done', 'Unlocked');
return {
ok: true,
result,
payment,
contentType: ct,
status: res.status,
network: payment.network || accept?.network || null,
payer: payment.payer || payerAddress || null,
transaction: payment.transaction || null,
};
}
// ────────────────────────────────────────────────────────────── Solana pay ───
export async function paySolana({ accept, resourceUrl, walletName, onStatus, origin, request }) {
accept = normalizeAccept(accept);
const apiOrigin = origin || (typeof location !== 'undefined' ? location.origin : '');
const label = walletName === 'solflare' ? 'Solflare' : 'Phantom';
const provider = getSolanaProvider(walletName);
if (!provider || typeof provider.connect !== 'function') {
if (initiateMobileRedirect(walletName, label, onStatus)) throw mobileRedirectError();
throw walletNotFound(walletName);
}
onStatus?.('connecting', `Opening ${label}…`);
const conn = await provider.connect();
const payerAddress = (conn?.publicKey || provider.publicKey)?.toString();
if (!payerAddress) throw new Error(`${label} did not return a public key`);
// Pre-flight: don't make the buyer sign a doomed transaction (fail-open).
onStatus?.('building', 'Checking your balance…');
await assertSufficientBalance({ accept, owner: payerAddress });
onStatus?.('building', 'Building payment…');
const prep = await postJson(
`${apiOrigin}/api/x402-checkout?action=prepare`,
buildPrepareBody(accept, payerAddress),
);
onStatus?.('signing', `Approve the payment in ${label}…`);
const txBytes = base64ToUint8Array(prep.tx_base64);
const web3 = await loadSolanaWeb3();
const tx = web3.VersionedTransaction.deserialize(txBytes);
// The wallet adds the buyer's signature; the facilitator's fee-payer signature
// is added during /settle.
const signed = await provider.signTransaction(tx);
const signedB64 = uint8ArrayToBase64(signed.serialize());
onStatus?.('confirming', 'Settling on-chain…');
const enc = await postJson(`${apiOrigin}/api/x402-checkout?action=encode`, {
accept,
signed_tx_base64: signedB64,
resource_url: resourceUrl,
});
return executePaid({ xPayment: enc.x_payment, resourceUrl, onStatus, accept, payerAddress, request });
}
// ───────────────────────────────────────────────────────────────── EVM pay ───
async function resolveEvmProvider(walletName, onStatus) {
if (walletName === 'walletconnect') {
const projectId = getWcProjectId();
if (!projectId) {
const err = new Error(
'WalletConnect is not configured here. Use MetaMask or Coinbase Wallet, or pay with a Solana wallet.',
);
err.code = 'wc_unconfigured';
throw err;
}
onStatus?.('connecting', 'Opening WalletConnect…');
// WalletConnect glue is a public/ runtime asset, not a bundled module.
// Keep the specifier non-static (+ @vite-ignore) so Vite's import-analysis
// doesn't try to resolve a /public path at build/test time; the browser
// loads it from the served URL at runtime only.
const wcProviderUrl = '/wallet/wc-provider.js';
const { initWCProvider } = await import(/* @vite-ignore */ wcProviderUrl);
const wc = await initWCProvider({
projectId,
optionalChains: Object.values(EVM_NETWORKS).map((n) => n.chainId),
});
await wc.enable();
return wc;
}
const provider = getEvmProvider(walletName);
if (!provider || typeof provider.request !== 'function') {
const label = WALLET_LABELS[walletName] || 'wallet';
if (initiateMobileRedirect(walletName, label, onStatus)) throw mobileRedirectError();
throw walletNotFound(walletName);
}
return provider;
}
function getWcProjectId() {
if (typeof document !== 'undefined') {
const meta = document.querySelector('meta[name="x402-wc-project-id"]');
if (meta?.content) return meta.content;
}
if (typeof window !== 'undefined' && window.WALLETCONNECT_PROJECT_ID) {
return window.WALLETCONNECT_PROJECT_ID;
}
return null;
}
export async function payEvm({ accept, resourceUrl, walletName, onStatus, request }) {
accept = normalizeAccept(accept);
const meta = EVM_NETWORKS[accept.network];
if (!meta) throw new Error(`Unsupported EVM network ${accept.network}`);
const label = WALLET_LABELS[walletName] || 'wallet';
const eth = await resolveEvmProvider(walletName, onStatus);
onStatus?.('connecting', `Opening ${label}…`);
const accounts = await eth.request({ method: 'eth_requestAccounts' });
const payerAddress = accounts?.[0];
if (!payerAddress) throw new Error(`${label} did not return an account`);
// Switch to the required chain if the wallet is elsewhere.
const currentChainHex = await eth.request({ method: 'eth_chainId' });
const desiredChainHex = '0x' + meta.chainId.toString(16);
if (currentChainHex !== desiredChainHex) {
onStatus?.('connecting', `Switch ${label} to ${meta.name}…`);
try {
await eth.request({
method: 'wallet_switchEthereumChain',
params: [{ chainId: desiredChainHex }],
});
} catch {
throw new Error(`Switch ${label} to ${meta.name} (${desiredChainHex}) and try again`);
}
}
// Pre-flight: catch an underfunded wallet before the signature prompt (fail-open).
onStatus?.('signing', 'Checking your balance…');
await assertSufficientBalance({ accept, owner: payerAddress, provider: eth });
onStatus?.('signing', `Authorize payment in ${label}…`);
const { typedData, authorization } = buildEip3009TypedData({
accept,
payerAddress,
chainId: meta.chainId,
});
const signature = await eth.request({
method: 'eth_signTypedData_v4',
params: [payerAddress, JSON.stringify(typedData)],
});
onStatus?.('confirming', 'Settling on-chain…');
const paymentPayload = buildEvmPaymentPayload({
accept,
signature,
authorization,
resourceUrl,
});
const xPayment = b64encode(paymentPayload);
return executePaid({ xPayment, resourceUrl, onStatus, accept, payerAddress, request });
}
// ─────────────────────────────────────────────────────────── dispatcher ──────
// Single entry point for the paywall controller. Routes a wallet button to the
// correct chain-specific payer based on the network of the matching `accept`.
export async function pay({ accept, resourceUrl, walletName, onStatus, origin, request }) {
// Inside the three.ws iOS app, payments open in Safari (ios/src/native-bridge.js
// shows the sheet that takes the visitor there).
if (globalThis.threeWsNative?.requireSafari?.() === true) {
throw Object.assign(new Error('Payments continue in Safari.'), { code: 'native_handoff' });
}
if (isSolanaNetwork(accept?.network)) {
return paySolana({ accept, resourceUrl, walletName, onStatus, origin, request });
}
if (isEvmNetwork(accept?.network)) {
return payEvm({ accept, resourceUrl, walletName, onStatus, request });
}
throw new Error(`Unsupported network ${accept?.network}`);
}
// Attach to window for the classic paywall.js controller.
if (typeof window !== 'undefined') {
window.PaywallWallet = Object.freeze({
pay,
paySolana,
payEvm,
isSolanaNetwork,
isEvmNetwork,
isEip3009Accept,
resolveResourceUrl,
explorerUrl,
getSolanaProvider,
getEvmProvider,
assertSufficientBalance,
readSolanaTokenBalance,
readEvmTokenBalance,
insufficientFundsError,
formatTokenAmount,
});
}