settld 0.2.0 → 0.2.2

package/src/core/wallet-funding-coinbase.js

@@ -0,0 +1,197 @@
+import { generateJwt } from "@coinbase/cdp-sdk/auth";
+
+function normalizeHttpUrl(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+
+function safeTrim(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeClientIp(value) {
+  const raw = safeTrim(value);
+  if (!raw) return null;
+  if (raw.startsWith("::ffff:")) return raw.slice(7);
+  return raw;
+}
+
+function mapBlockchainToCoinbaseNetwork(raw) {
+  const value = safeTrim(raw).toLowerCase();
+  if (!value) return null;
+  if (value === "base" || value === "base-mainnet" || value === "base_mainnet") return "base";
+  if (value === "ethereum" || value === "eth" || value === "ethereum-mainnet" || value === "ethereum_mainnet") return "ethereum";
+  if (value === "polygon" || value === "polygon-mainnet" || value === "polygon_mainnet") return "polygon";
+  if (value === "solana" || value === "sol") return "solana";
+  if (value === "arbitrum" || value === "arbitrum-mainnet" || value === "arbitrum_mainnet") return "arbitrum";
+  if (value === "optimism" || value === "optimism-mainnet" || value === "optimism_mainnet") return "optimism";
+  if (value === "bitcoin" || value === "btc") return "bitcoin";
+  return null;
+}
+
+function buildHostedUrl({ payBaseUrl, sessionToken, defaultNetwork, defaultAsset, redirectUrl, fiatCurrency, paymentMethod }) {
+  const u = new URL(payBaseUrl);
+  u.searchParams.set("sessionToken", sessionToken);
+  if (defaultNetwork) u.searchParams.set("defaultNetwork", defaultNetwork);
+  if (defaultAsset) u.searchParams.set("defaultAsset", defaultAsset);
+  if (redirectUrl) u.searchParams.set("redirectUrl", redirectUrl);
+  if (fiatCurrency) u.searchParams.set("fiatCurrency", fiatCurrency);
+  if (paymentMethod) u.searchParams.set("defaultPaymentMethod", paymentMethod);
+  return u.toString();
+}
+
+function hostedMethodUrls({
+  requestedMethod,
+  payBaseUrl,
+  sessionToken,
+  defaultNetwork,
+  defaultAsset,
+  redirectUrl,
+  fiatCurrency,
+  cardPaymentMethod,
+  bankPaymentMethod
+}) {
+  const cardUrl = buildHostedUrl({
+    payBaseUrl,
+    sessionToken,
+    defaultNetwork,
+    defaultAsset,
+    redirectUrl,
+    fiatCurrency,
+    paymentMethod: safeTrim(cardPaymentMethod) || null
+  });
+  const bankUrl = buildHostedUrl({
+    payBaseUrl,
+    sessionToken,
+    defaultNetwork,
+    defaultAsset,
+    redirectUrl,
+    fiatCurrency,
+    paymentMethod: safeTrim(bankPaymentMethod) || null
+  });
+
+  if (requestedMethod === "card") return { card: cardUrl, bank: null, preferredMethod: "card" };
+  if (requestedMethod === "bank") return { card: null, bank: bankUrl, preferredMethod: "bank" };
+  return { card: cardUrl, bank: bankUrl, preferredMethod: "card" };
+}
+
+function readJsonSafe(raw) {
+  try {
+    return JSON.parse(String(raw ?? ""));
+  } catch {
+    return null;
+  }
+}
+
+export async function buildCoinbaseHostedUrls({
+  requestedMethod = null,
+  walletAddress = null,
+  blockchain = null,
+  clientIp = null,
+  config = {},
+  fetchImpl = fetch,
+  generateJwtImpl = generateJwt
+} = {}) {
+  const apiKeyId = safeTrim(config.apiKeyId);
+  const apiKeySecret = safeTrim(config.apiKeySecret);
+  if (!apiKeyId || !apiKeySecret) {
+    return { card: null, bank: null, preferredMethod: null, provider: "coinbase", unavailableReason: "MISSING_API_KEYS" };
+  }
+  const normalizedApiKeySecret = apiKeySecret.includes("\\n") ? apiKeySecret.replace(/\\n/g, "\n") : apiKeySecret;
+
+  const tokenUrl = normalizeHttpUrl(config.tokenUrl ?? "https://api.developer.coinbase.com/onramp/v1/token");
+  const payBaseUrl = normalizeHttpUrl(config.payBaseUrl ?? "https://pay.coinbase.com/buy/select-asset");
+  if (!tokenUrl || !payBaseUrl) {
+    return { card: null, bank: null, preferredMethod: null, provider: "coinbase", unavailableReason: "INVALID_URLS" };
+  }
+
+  const parsedTokenUrl = new URL(tokenUrl);
+  const networkOverride = safeTrim(config.destinationNetwork);
+  const destinationNetwork = networkOverride || mapBlockchainToCoinbaseNetwork(blockchain);
+  if (!destinationNetwork) {
+    return { card: null, bank: null, preferredMethod: null, provider: "coinbase", unavailableReason: "UNSUPPORTED_NETWORK" };
+  }
+
+  const destinationAddress = safeTrim(walletAddress);
+  if (!destinationAddress) {
+    return { card: null, bank: null, preferredMethod: null, provider: "coinbase", unavailableReason: "MISSING_WALLET_ADDRESS" };
+  }
+
+  const purchaseAsset = safeTrim(config.purchaseAsset).toUpperCase() || "USDC";
+  const fiatCurrency = safeTrim(config.fiatCurrency).toUpperCase() || "USD";
+  const redirectUrl = normalizeHttpUrl(config.redirectUrl);
+  const partnerUserRef = safeTrim(config.partnerUserRef) || null;
+  const resolvedClientIp = normalizeClientIp(config.clientIp) || normalizeClientIp(clientIp) || null;
+
+  const jwt = await generateJwtImpl({
+    apiKeyId,
+    apiKeySecret: normalizedApiKeySecret,
+    requestMethod: "POST",
+    requestHost: parsedTokenUrl.host,
+    requestPath: parsedTokenUrl.pathname,
+    expiresIn: 120
+  });
+
+  const requestBody = {
+    addresses: [{
+      address: destinationAddress,
+      blockchains: [destinationNetwork]
+    }],
+    assets: [purchaseAsset]
+  };
+  if (resolvedClientIp) requestBody.clientIp = resolvedClientIp;
+  if (partnerUserRef) requestBody.partnerUserRef = partnerUserRef;
+
+  const res = await fetchImpl(tokenUrl, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${jwt}`,
+      "content-type": "application/json",
+      accept: "application/json"
+    },
+    body: JSON.stringify(requestBody)
+  });
+  const raw = await res.text();
+  const json = readJsonSafe(raw);
+  if (!res.ok) {
+    const detail = json && typeof json === "object" ? json : { message: raw || `HTTP ${res.status}` };
+    const err = new Error(`coinbase session token request failed (${res.status})`);
+    err.detail = detail;
+    throw err;
+  }
+
+  const sessionToken = safeTrim(json?.token || json?.sessionToken || json?.session?.token);
+  if (!sessionToken) {
+    const err = new Error("coinbase session token response missing token");
+    err.detail = json;
+    throw err;
+  }
+
+  const urls = hostedMethodUrls({
+    requestedMethod,
+    payBaseUrl,
+    sessionToken,
+    defaultNetwork: destinationNetwork,
+    defaultAsset: purchaseAsset,
+    redirectUrl,
+    fiatCurrency,
+    cardPaymentMethod: config.cardPaymentMethod,
+    bankPaymentMethod: config.bankPaymentMethod
+  });
+
+  return {
+    ...urls,
+    provider: "coinbase",
+    sessionToken,
+    destinationNetwork,
+    purchaseAsset,
+    fiatCurrency
+  };
+}

package/src/core/wallet-funding-hosted.js

@@ -0,0 +1,155 @@
+import crypto from "node:crypto";
+
+function normalizeHttpUrl(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+
+function parseCsvList(raw) {
+  const input = String(raw ?? "").trim();
+  if (!input) return [];
+  return [...new Set(input.split(",").map((x) => String(x ?? "").trim()).filter(Boolean))];
+}
+
+function normalizeOnramperNetworkId(raw) {
+  const value = String(raw ?? "").trim();
+  if (!value) return null;
+  const key = value.toLowerCase();
+  if (key === "base-sepolia") return "base_sepolia";
+  if (key === "base") return "base";
+  if (key === "ethereum" || key === "eth") return "ethereum";
+  if (key === "ethereum-sepolia" || key === "sepolia") return "ethereum_sepolia";
+  if (key === "polygon" || key === "matic") return "polygon";
+  if (key === "solana" || key === "sol") return "solana";
+  return key.replace(/[^a-z0-9_-]+/g, "_");
+}
+
+function normalizedList(raw) {
+  return parseCsvList(raw)
+    .map((x) => String(x).trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function addIfPresent(searchParams, key, value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return;
+  searchParams.set(key, raw);
+}
+
+function buildSensitiveSignature({ signingSecret, sensitivePairs }) {
+  const secret = String(signingSecret ?? "").trim();
+  if (!secret || !Array.isArray(sensitivePairs) || !sensitivePairs.length) return null;
+  const rows = sensitivePairs
+    .map((entry) => {
+      const k = String(entry?.key ?? "").trim();
+      const v = String(entry?.value ?? "").trim();
+      if (!k || !v) return null;
+      return { key: k, value: v };
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.key.localeCompare(b.key));
+  if (!rows.length) return null;
+  const signContent = rows.map(({ key, value }) => `${key}=${value}`).join("&");
+  return crypto.createHmac("sha256", secret).update(signContent, "utf8").digest("hex");
+}
+
+function buildMethodUrl({
+  baseUrl,
+  apiKey,
+  method,
+  defaultFiat,
+  defaultCrypto,
+  onlyCryptos,
+  onlyCryptoNetworks,
+  walletAddress,
+  networkId,
+  signingSecret,
+  successRedirectUrl,
+  failureRedirectUrl
+}) {
+  const u = new URL(baseUrl);
+  const sp = u.searchParams;
+  sp.set("apiKey", apiKey);
+  sp.set("mode", "buy");
+
+  addIfPresent(sp, "defaultFiat", defaultFiat);
+  addIfPresent(sp, "defaultCrypto", defaultCrypto);
+
+  if (onlyCryptos.length) sp.set("onlyCryptos", onlyCryptos.join(","));
+  if (onlyCryptoNetworks.length) sp.set("onlyCryptoNetworks", onlyCryptoNetworks.join(","));
+
+  if (method === "card") sp.set("defaultPaymentMethod", "creditcard");
+  if (method === "bank") sp.set("defaultPaymentMethod", "banktransfer");
+
+  addIfPresent(sp, "successRedirectUrl", successRedirectUrl);
+  addIfPresent(sp, "failureRedirectUrl", failureRedirectUrl);
+
+  const sensitivePairs = [];
+  if (walletAddress && networkId && signingSecret) {
+    const networkWallets = `${networkId}:${walletAddress}`;
+    sp.set("networkWallets", networkWallets);
+    sensitivePairs.push({ key: "networkWallets", value: networkWallets });
+  }
+
+  const signature = buildSensitiveSignature({ signingSecret, sensitivePairs });
+  if (signature) sp.set("signature", signature);
+
+  return u.toString();
+}
+
+export function buildOnramperHostedUrls({
+  requestedMethod = null,
+  walletAddress = null,
+  blockchain = null,
+  config = {}
+} = {}) {
+  const apiKey = String(config.apiKey ?? "").trim();
+  if (!apiKey) return { card: null, bank: null, preferredMethod: null, provider: "onramper" };
+
+  const baseUrl = normalizeHttpUrl(config.baseUrl ?? "https://buy.onramper.com");
+  if (!baseUrl) return { card: null, bank: null, preferredMethod: null, provider: "onramper" };
+
+  const onlyCryptos = normalizedList(config.onlyCryptos);
+  const onlyCryptoNetworks = normalizedList(config.onlyCryptoNetworks);
+  const defaultCrypto = String(config.defaultCrypto ?? "usdc").trim().toLowerCase();
+  const defaultFiat = String(config.defaultFiat ?? "usd").trim().toLowerCase();
+
+  const configuredNetworkId = normalizeOnramperNetworkId(config.networkId);
+  const inferredNetworkId = normalizeOnramperNetworkId(blockchain);
+  const networkId = configuredNetworkId || inferredNetworkId;
+  const signingSecret = String(config.signingSecret ?? "").trim();
+  const successRedirectUrl = normalizeHttpUrl(config.successRedirectUrl);
+  const failureRedirectUrl = normalizeHttpUrl(config.failureRedirectUrl);
+
+  const make = (method) =>
+    buildMethodUrl({
+      baseUrl,
+      apiKey,
+      method,
+      defaultFiat,
+      defaultCrypto,
+      onlyCryptos,
+      onlyCryptoNetworks,
+      walletAddress: String(walletAddress ?? "").trim() || null,
+      networkId,
+      signingSecret,
+      successRedirectUrl,
+      failureRedirectUrl
+    });
+
+  let card = make("card");
+  let bank = make("bank");
+
+  if (requestedMethod === "card") bank = null;
+  if (requestedMethod === "bank") card = null;
+
+  const preferredMethod = card ? "card" : bank ? "bank" : null;
+  return { card, bank, preferredMethod, provider: "onramper" };
+}

package/src/core/wallet-provider-bootstrap.js

@@ -86,6 +86,44 @@ function pickUsdcTokenId(payload) {
   return null;
 }
 
+function pickUsdcBalance(payload, { tokenIdHint = null } = {}) {
+  const root = payload && typeof payload === "object" ? payload : {};
+  const balances =
+    (Array.isArray(root?.data?.tokenBalances) && root.data.tokenBalances) ||
+    (Array.isArray(root?.tokenBalances) && root.tokenBalances) ||
+    [];
+  const normalizedHint = String(tokenIdHint ?? "").trim();
+  const ranked = [];
+  for (const row of balances) {
+    if (!row || typeof row !== "object") continue;
+    const token = row.token && typeof row.token === "object" ? row.token : null;
+    const tokenId = String(token?.id ?? row.tokenId ?? row.id ?? "").trim();
+    const symbol = String(token?.symbol ?? row.symbol ?? "").trim().toUpperCase();
+    const amountRaw = row.amount ?? row.amountUsdc ?? row.balance ?? null;
+    const amountText = amountRaw === null || amountRaw === undefined ? "" : String(amountRaw).trim();
+    if (!amountText) continue;
+    const amount = Number(amountText);
+    if (!Number.isFinite(amount) || amount < 0) continue;
+    const score =
+      normalizedHint && tokenId === normalizedHint
+        ? 3
+        : symbol === "USDC"
+          ? 2
+          : tokenId && normalizedHint && tokenId.toLowerCase().includes("usdc")
+            ? 1
+            : 0;
+    ranked.push({
+      score,
+      tokenId: tokenId || null,
+      symbol: symbol || null,
+      amount,
+      amountText
+    });
+  }
+  ranked.sort((a, b) => b.score - a.score || b.amount - a.amount);
+  return ranked[0] ?? null;
+}
+
 function inferModeFromBaseUrl(baseUrl) {
   const u = normalizeHttpUrl(baseUrl);
   if (!u) return null;
@@ -198,6 +236,27 @@ async function resolveUsdcTokenId({ baseUrl, apiKey, walletIds, fetchImpl = fetc
   return null;
 }
 
+async function resolveWalletUsdcBalance({ baseUrl, apiKey, walletId, tokenIdHint = null, fetchImpl = fetch }) {
+  const out = await callCircle({
+    baseUrl,
+    apiKey,
+    method: "GET",
+    endpoint: `/v1/w3s/wallets/${encodeURIComponent(walletId)}/balances`,
+    fetchImpl
+  });
+  if (out.status < 200 || out.status >= 300) {
+    throw new Error(`wallet balance lookup failed for ${walletId} (HTTP ${out.status})`);
+  }
+  const picked = pickUsdcBalance(out.json, { tokenIdHint });
+  return {
+    walletId,
+    usdcAmount: picked ? picked.amount : null,
+    usdcAmountText: picked ? picked.amountText : null,
+    tokenId: picked?.tokenId ?? null,
+    symbol: picked?.symbol ?? null
+  };
+}
+
 async function requestFaucet({ baseUrl, apiKey, address, blockchain, native, usdc, fetchImpl = fetch }) {
   const out = await callCircle({
     baseUrl,
@@ -229,6 +288,7 @@ export async function bootstrapCircleProvider({
   escrowWalletId = null,
   tokenIdUsdc = null,
   faucet = null,
+  includeBalances = false,
   includeApiKey = false,
   entitySecretHex = null,
   fetchImpl = fetch
@@ -284,6 +344,40 @@ export async function bootstrapCircleProvider({
     throw new Error("could not discover USDC token id; pass tokenIdUsdc explicitly");
   }
 
+  let balances = null;
+  if (includeBalances) {
+    try {
+      const [spendBalance, escrowBalance] = await Promise.all([
+        resolveWalletUsdcBalance({
+          baseUrl: detected.baseUrl,
+          apiKey: circleApiKey,
+          walletId: chosen.spendWalletId,
+          tokenIdHint: resolvedTokenIdUsdc,
+          fetchImpl
+        }),
+        resolveWalletUsdcBalance({
+          baseUrl: detected.baseUrl,
+          apiKey: circleApiKey,
+          walletId: chosen.escrowWalletId,
+          tokenIdHint: resolvedTokenIdUsdc,
+          fetchImpl
+        })
+      ]);
+      balances = {
+        asOf: new Date().toISOString(),
+        spend: spendBalance,
+        escrow: escrowBalance
+      };
+    } catch (err) {
+      balances = {
+        asOf: new Date().toISOString(),
+        error: err?.message ?? "balance_lookup_failed",
+        spend: null,
+        escrow: null
+      };
+    }
+  }
+
   const faucetEnabled =
     typeof faucet === "boolean"
       ? faucet
@@ -342,6 +436,7 @@ export async function bootstrapCircleProvider({
       escrow: escrowMeta
     },
     tokenIdUsdc: resolvedTokenIdUsdc,
+    balances,
     entitySecretHex: resolvedEntitySecretHex,
     faucetEnabled,
     faucetResults,