arc-builder-kit 0.2.0__py3-none-any.whl

arc_builder_kit/examples/arc-testnet-wallet-send-gate/wallet-send-gate.js

@@ -0,0 +1,472 @@
+const ARC_TESTNET = Object.freeze({
+  name: 'Arc Testnet',
+  chainId: 5042002,
+  chainIdHex: '0x4cef52',
+  rpcUrl: 'https://rpc.testnet.arc.network',
+  explorerUrl: 'https://testnet.arcscan.app',
+  usdcAddress: '0x3600000000000000000000000000000000000000',
+  usdcDecimals: 6,
+  nativeGasDecimals: 18,
+  maxAmountBaseUnits: 1000000n,
+});
+
+const REQUIRED_CONFIRMATION = 'SEND ARC TESTNET USDC';
+const FEATURE_GATE_NAME = 'enableArcTestnetSend';
+const FEATURE_GATE_VALUE = 'reviewed-testnet-only';
+const TRANSFER_SELECTOR = 'a9059cbb';
+const ALLOWED_WALLET_METHODS = new Set([
+  'eth_requestAccounts',
+  'eth_accounts',
+  'eth_chainId',
+  'wallet_switchEthereumChain',
+  'wallet_addEthereumChain',
+  'eth_sendTransaction',
+]);
+
+const elements = {
+  featureGateStatus: document.querySelector('#feature-gate-status'),
+  riskAcknowledgement: document.querySelector('#risk-acknowledgement'),
+  walletStatus: document.querySelector('#wallet-status'),
+  providerState: document.querySelector('#provider-state'),
+  accountState: document.querySelector('#account-state'),
+  chainState: document.querySelector('#chain-state'),
+  connectWallet: document.querySelector('#connect-wallet'),
+  switchNetwork: document.querySelector('#switch-network'),
+  recipient: document.querySelector('#recipient'),
+  amount: document.querySelector('#amount'),
+  expiry: document.querySelector('#expiry'),
+  memo: document.querySelector('#memo'),
+  freezeIntent: document.querySelector('#freeze-intent'),
+  intentStatus: document.querySelector('#intent-status'),
+  frozenPayload: document.querySelector('#frozen-payload'),
+  confirmationPhrase: document.querySelector('#confirmation-phrase'),
+  finalSendConfirmation: document.querySelector('#final-send-confirmation'),
+  sendTransaction: document.querySelector('#send-transaction'),
+  sendStatus: document.querySelector('#send-status'),
+  sendResult: document.querySelector('#send-result'),
+  transactionLink: document.querySelector('#transaction-link'),
+  guardList: document.querySelector('#guard-list'),
+  methodLog: document.querySelector('#method-log'),
+};
+
+const state = {
+  featureGatePresent: new URLSearchParams(window.location.search).get(FEATURE_GATE_NAME) === FEATURE_GATE_VALUE,
+  topLevelContext: window.top === window.self,
+  provider: window.ethereum || null,
+  account: '',
+  chainIdHex: '',
+  frozenIntent: null,
+  frozenDraft: null,
+  sendAttempted: false,
+  transactionHash: '',
+  methodNames: [],
+};
+
+function normalizeHex(value) {
+  return String(value || '').toLowerCase();
+}
+
+function isAddress(value) {
+  return /^0x[a-fA-F0-9]{40}$/.test(String(value || '').trim());
+}
+
+function isNonZeroAddress(value) {
+  return isAddress(value) && !/^0x0{40}$/i.test(String(value || '').trim());
+}
+
+function parseUsdcAmount(rawValue) {
+  const value = String(rawValue || '').trim();
+  if (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,6})?$/.test(value)) {
+    throw new Error('Amount must be a plain positive decimal with at most 6 fractional digits.');
+  }
+  const [whole, fraction = ''] = value.split('.');
+  const baseUnits = (BigInt(whole) * 1000000n) + BigInt(fraction.padEnd(6, '0'));
+  if (baseUnits <= 0n) throw new Error('Amount must be greater than zero.');
+  if (baseUnits > ARC_TESTNET.maxAmountBaseUnits) throw new Error('Amount exceeds the 1.00 USDC safety cap.');
+  return { decimal: value, baseUnits };
+}
+
+function encodeTransferCalldata(recipient, amountBaseUnits) {
+  const addressWord = recipient.toLowerCase().replace(/^0x/, '').padStart(64, '0');
+  const amountWord = amountBaseUnits.toString(16).padStart(64, '0');
+  return `0x${TRANSFER_SELECTOR}${addressWord}${amountWord}`;
+}
+
+function decodeTransferCalldata(data) {
+  const normalized = String(data || '').toLowerCase();
+  if (!new RegExp(`^0x${TRANSFER_SELECTOR}[0-9a-f]{128}$`).test(normalized)) {
+    throw new Error('Calldata is not the pinned ERC-20 transfer(address,uint256) shape.');
+  }
+  return {
+    method: 'transfer(address,uint256)',
+    recipient: `0x${normalized.slice(34, 74)}`,
+    amountBaseUnits: BigInt(`0x${normalized.slice(74, 138)}`).toString(),
+  };
+}
+
+function currentIntent() {
+  const recipient = elements.recipient.value.trim().toLowerCase();
+  if (!isNonZeroAddress(recipient)) {
+    throw new Error('Recipient must be a non-zero 0x-prefixed 20-byte address.');
+  }
+  if (recipient === ARC_TESTNET.usdcAddress.toLowerCase()) {
+    throw new Error('Recipient cannot be the pinned USDC token contract address.');
+  }
+  const amount = parseUsdcAmount(elements.amount.value);
+  const expiryText = elements.expiry.value;
+  const expiryMs = Date.parse(expiryText);
+  const now = Date.now();
+  if (!expiryText || !Number.isFinite(expiryMs) || expiryMs <= now) {
+    throw new Error('Expiry must be a valid future time.');
+  }
+  if (expiryMs > now + (24 * 60 * 60 * 1000)) {
+    throw new Error('Expiry must be within 24 hours.');
+  }
+  const memo = elements.memo.value.trim();
+  if (!memo) throw new Error('Memo is required for visible intent binding.');
+  if (memo.length > 180) throw new Error('Memo must be 180 characters or fewer.');
+  return {
+    network: ARC_TESTNET.name,
+    chainId: ARC_TESTNET.chainId,
+    chainIdHex: ARC_TESTNET.chainIdHex,
+    account: state.account.toLowerCase(),
+    token: ARC_TESTNET.usdcAddress,
+    tokenDecimals: ARC_TESTNET.usdcDecimals,
+    recipient,
+    amountDecimal: amount.decimal,
+    amountBaseUnits: amount.baseUnits.toString(),
+    memo,
+    expiry: new Date(expiryMs).toISOString(),
+  };
+}
+
+function buildDraft(intent) {
+  const data = encodeTransferCalldata(intent.recipient, BigInt(intent.amountBaseUnits));
+  const decoded = decodeTransferCalldata(data);
+  return {
+    type: 'guarded_arc_testnet_erc20_transfer',
+    chainId: ARC_TESTNET.chainIdHex,
+    from: intent.account,
+    to: ARC_TESTNET.usdcAddress,
+    value: '0x0',
+    data,
+    decoded,
+  };
+}
+
+function intentMatchesFrozen() {
+  if (!state.frozenIntent) return false;
+  try {
+    return JSON.stringify(currentIntent()) === JSON.stringify(state.frozenIntent);
+  } catch (_error) {
+    return false;
+  }
+}
+
+function draftMatchesFrozenIntent() {
+  if (!state.frozenIntent || !state.frozenDraft) return false;
+  try {
+    const rebuilt = buildDraft(state.frozenIntent);
+    return (
+      JSON.stringify(rebuilt) === JSON.stringify(state.frozenDraft)
+      && rebuilt.chainId === ARC_TESTNET.chainIdHex
+      && rebuilt.to === ARC_TESTNET.usdcAddress
+      && rebuilt.value === '0x0'
+      && rebuilt.decoded.recipient === state.frozenIntent.recipient
+      && rebuilt.decoded.amountBaseUnits === state.frozenIntent.amountBaseUnits
+    );
+  } catch (_error) {
+    return false;
+  }
+}
+
+function buildGuardReport() {
+  const riskAcknowledged = elements.riskAcknowledgement.checked;
+  const providerAvailable = Boolean(state.provider && typeof state.provider.request === 'function');
+  const accountValid = isNonZeroAddress(state.account);
+  const chainMatches = normalizeHex(state.chainIdHex) === ARC_TESTNET.chainIdHex;
+  const phraseMatches = elements.confirmationPhrase.value === REQUIRED_CONFIRMATION;
+  const finalChecked = elements.finalSendConfirmation.checked;
+  let intentValid = false;
+  let intentError = '';
+  try {
+    currentIntent();
+    intentValid = true;
+  } catch (error) {
+    intentError = error.message;
+  }
+  const frozen = Boolean(state.frozenIntent && state.frozenDraft);
+  const frozenParity = frozen && intentMatchesFrozen() && draftMatchesFrozenIntent();
+  const checks = [
+    ['feature-gate', state.featureGatePresent, 'Exact reviewed-testnet query gate is present.'],
+    ['top-level-context', state.topLevelContext, 'Page is running in a top-level browsing context, not an embedded frame.'],
+    ['risk-ack', riskAcknowledged, 'Risk acknowledgement is checked.'],
+    ['provider', providerAvailable, 'Injected EVM wallet provider is available.'],
+    ['account', accountValid, 'Connected account is a valid EVM address.'],
+    ['chain', chainMatches, `Wallet reports Arc Testnet ${ARC_TESTNET.chainIdHex}.`],
+    ['intent', intentValid, intentValid ? 'Intent fields are valid.' : intentError],
+    ['frozen-parity', frozenParity, 'Current fields and deterministic calldata match the frozen review.'],
+    ['typed-confirmation', phraseMatches, 'Exact confirmation phrase matches.'],
+    ['final-checkbox', finalChecked, 'Final human confirmation is checked.'],
+    ['one-shot-lock', !state.sendAttempted, 'No wallet transaction attempt has occurred this page load.'],
+  ];
+  return {
+    passed: checks.every((check) => check[1]),
+    checks: checks.map(([id, passed, detail]) => ({ id, passed, detail })),
+  };
+}
+
+function canAttemptSend() {
+  return buildGuardReport().passed;
+}
+
+function recordMethod(method) {
+  state.methodNames.push({ method, requestedAt: new Date().toISOString() });
+  renderMethodLog();
+}
+
+async function requestWallet(request) {
+  if (!state.provider || typeof state.provider.request !== 'function') {
+    throw new Error('Injected wallet provider is unavailable.');
+  }
+  if (!ALLOWED_WALLET_METHODS.has(request.method)) {
+    throw new Error('Wallet method is outside the reviewed Arc Testnet allowlist.');
+  }
+  recordMethod(request.method);
+  return state.provider.request(request);
+}
+
+function safeWalletError(error) {
+  const code = Number(error && error.code);
+  if (code === 4001) return 'Wallet request was rejected by the user.';
+  if (code === 4902) return 'Arc Testnet is not configured in this wallet.';
+  if (code === -32002) return 'A wallet request is already pending. Open the wallet extension.';
+  return 'Wallet request failed. Review the wallet UI and reload before another send attempt.';
+}
+
+function clearFrozenReview(reason) {
+  state.frozenIntent = null;
+  state.frozenDraft = null;
+  elements.finalSendConfirmation.checked = false;
+  elements.confirmationPhrase.value = '';
+  elements.frozenPayload.textContent = reason;
+}
+
+async function connectWallet() {
+  if (!state.featureGatePresent || !state.topLevelContext || !elements.riskAcknowledgement.checked) return;
+  try {
+    const accounts = await requestWallet({ method: 'eth_requestAccounts', params: [] });
+    const chainIdHex = await requestWallet({ method: 'eth_chainId', params: [] });
+    state.account = Array.isArray(accounts) && isNonZeroAddress(accounts[0]) ? accounts[0] : '';
+    state.chainIdHex = normalizeHex(chainIdHex);
+    clearFrozenReview('Wallet state changed. Freeze the intent again after reviewing the connected account and chain.');
+  } catch (error) {
+    elements.sendResult.textContent = safeWalletError(error);
+  }
+  render();
+}
+
+async function switchToArcTestnet() {
+  if (!state.featureGatePresent || !state.topLevelContext || !elements.riskAcknowledgement.checked) return;
+  try {
+    try {
+      await requestWallet({
+        method: 'wallet_switchEthereumChain',
+        params: [{ chainId: ARC_TESTNET.chainIdHex }],
+      });
+    } catch (error) {
+      if (Number(error && error.code) !== 4902) throw error;
+      await requestWallet({
+        method: 'wallet_addEthereumChain',
+        params: [{
+          chainId: ARC_TESTNET.chainIdHex,
+          chainName: ARC_TESTNET.name,
+          nativeCurrency: { name: 'USDC', symbol: 'USDC', decimals: ARC_TESTNET.nativeGasDecimals },
+          rpcUrls: [ARC_TESTNET.rpcUrl],
+          blockExplorerUrls: [ARC_TESTNET.explorerUrl],
+        }],
+      });
+    }
+    state.chainIdHex = normalizeHex(await requestWallet({ method: 'eth_chainId', params: [] }));
+    clearFrozenReview('Network state changed. Freeze the intent again after proving Arc Testnet.');
+  } catch (error) {
+    elements.sendResult.textContent = safeWalletError(error);
+  }
+  render();
+}
+
+function freezeIntent() {
+  try {
+    const report = buildGuardReport();
+    const prerequisiteIds = ['feature-gate', 'top-level-context', 'risk-ack', 'provider', 'account', 'chain', 'intent'];
+    const failedPrerequisite = report.checks.find((check) => prerequisiteIds.includes(check.id) && !check.passed);
+    if (failedPrerequisite) {
+      throw new Error(failedPrerequisite.detail || 'Resolve the visible intent guards before freezing.');
+    }
+    state.frozenIntent = currentIntent();
+    state.frozenDraft = buildDraft(state.frozenIntent);
+    elements.finalSendConfirmation.checked = false;
+    elements.confirmationPhrase.value = '';
+    elements.frozenPayload.textContent = JSON.stringify({
+      intent: state.frozenIntent,
+      transactionRequest: state.frozenDraft,
+      safety: {
+        humanApprovalRequired: true,
+        oneAttemptPerPageLoad: true,
+        automaticRetry: false,
+        retryRule: 'No automatic retry',
+        privateKeyHandling: false,
+        custody: false,
+      },
+    }, null, 2);
+    elements.sendResult.textContent = 'Intent frozen. Compare every field before final confirmation.';
+  } catch (error) {
+    clearFrozenReview(error.message);
+    elements.sendResult.textContent = error.message;
+  }
+  render();
+}
+
+async function requestOneTransaction() {
+  if (!canAttemptSend()) return;
+  state.sendAttempted = true;
+  render();
+  try {
+    const liveChain = normalizeHex(await requestWallet({ method: 'eth_chainId', params: [] }));
+    const liveAccounts = await requestWallet({ method: 'eth_accounts', params: [] });
+    const liveAccount = Array.isArray(liveAccounts) && isNonZeroAddress(liveAccounts[0]) ? liveAccounts[0].toLowerCase() : '';
+    if (liveChain !== ARC_TESTNET.chainIdHex || liveAccount !== state.frozenIntent.account) {
+      throw new Error('Wallet chain or account changed after review.');
+    }
+    if (!intentMatchesFrozen() || !draftMatchesFrozenIntent()) {
+      throw new Error('Frozen payload parity failed immediately before wallet handoff.');
+    }
+
+    const transactionHash = await requestWallet({
+      method: 'eth_sendTransaction',
+      params: [{
+        chainId: state.frozenDraft.chainId,
+        from: state.frozenDraft.from,
+        to: state.frozenDraft.to,
+        value: state.frozenDraft.value,
+        data: state.frozenDraft.data,
+      }],
+    });
+    if (!/^0x[a-fA-F0-9]{64}$/.test(String(transactionHash || ''))) {
+      throw new Error('Wallet did not return a valid transaction hash.');
+    }
+    state.transactionHash = transactionHash;
+    elements.sendResult.textContent = 'Wallet returned a transaction hash. Status is submitted/pending, not confirmed.';
+    elements.transactionLink.href = `${ARC_TESTNET.explorerUrl}/tx/${transactionHash}`;
+    elements.transactionLink.hidden = false;
+  } catch (error) {
+    const internalMessage = error instanceof Error ? error.message : '';
+    elements.sendResult.textContent = internalMessage.startsWith('Wallet chain') || internalMessage.startsWith('Frozen payload')
+      ? internalMessage
+      : safeWalletError(error);
+  }
+  render();
+}
+
+function renderMethodLog() {
+  if (!state.methodNames.length) {
+    elements.methodLog.replaceChildren(Object.assign(document.createElement('li'), { textContent: 'No wallet methods requested.' }));
+    return;
+  }
+  elements.methodLog.replaceChildren(...state.methodNames.map((entry) => {
+    const item = document.createElement('li');
+    const code = document.createElement('code');
+    code.textContent = entry.method;
+    item.append(code, ` at ${entry.requestedAt}`);
+    return item;
+  }));
+}
+
+function renderGuards() {
+  const report = buildGuardReport();
+  elements.guardList.replaceChildren(...report.checks.map((check) => {
+    const item = document.createElement('li');
+    const verdict = document.createElement('strong');
+    verdict.className = check.passed ? 'pass' : 'fail';
+    verdict.textContent = check.passed ? 'PASS' : 'BLOCK';
+    item.append(verdict, check.detail);
+    return item;
+  }));
+  return report;
+}
+
+function render() {
+  const acknowledged = elements.riskAcknowledgement.checked;
+  const providerAvailable = Boolean(state.provider && typeof state.provider.request === 'function');
+  const chainMatches = normalizeHex(state.chainIdHex) === ARC_TESTNET.chainIdHex;
+  const report = renderGuards();
+
+  const reviewEnabled = state.featureGatePresent && state.topLevelContext && acknowledged;
+  elements.featureGateStatus.textContent = !state.topLevelContext ? 'blocked in embedded frame' : reviewEnabled ? 'enabled for review' : 'disabled';
+  elements.featureGateStatus.className = `status ${reviewEnabled ? 'pass' : 'fail'}`;
+  elements.providerState.textContent = providerAvailable ? 'Injected provider detected' : 'No injected provider';
+  elements.accountState.textContent = state.account || 'Not requested';
+  elements.chainState.textContent = state.chainIdHex || 'Not requested';
+  elements.walletStatus.textContent = state.account && chainMatches ? 'Arc Testnet proven' : 'not ready';
+  elements.walletStatus.className = `status ${state.account && chainMatches ? 'pass' : 'warn'}`;
+  elements.intentStatus.textContent = state.frozenIntent && intentMatchesFrozen() ? 'frozen / parity pass' : 'editable';
+  elements.intentStatus.className = `status ${state.frozenIntent && intentMatchesFrozen() ? 'pass' : 'warn'}`;
+  elements.sendStatus.textContent = state.transactionHash ? 'submitted / pending' : state.sendAttempted ? 'attempt locked' : report.passed ? 'ready for wallet' : 'blocked';
+  elements.sendStatus.className = `status ${state.transactionHash ? 'warn' : report.passed ? 'pass' : 'fail'}`;
+
+  elements.riskAcknowledgement.disabled = !state.featureGatePresent || !state.topLevelContext || state.sendAttempted;
+  elements.connectWallet.disabled = !state.featureGatePresent || !state.topLevelContext || !acknowledged || !providerAvailable || state.sendAttempted;
+  elements.switchNetwork.disabled = !state.featureGatePresent || !state.topLevelContext || !acknowledged || !providerAvailable || state.sendAttempted;
+  elements.freezeIntent.disabled = !state.featureGatePresent || !state.topLevelContext || !acknowledged || !providerAvailable || !state.account || !chainMatches || state.sendAttempted;
+  elements.sendTransaction.disabled = !report.passed;
+  for (const input of [elements.recipient, elements.amount, elements.expiry, elements.memo, elements.confirmationPhrase, elements.finalSendConfirmation]) {
+    input.disabled = state.sendAttempted;
+  }
+  renderMethodLog();
+}
+
+function setDefaultExpiry() {
+  const future = new Date(Date.now() + (30 * 60 * 1000));
+  const local = new Date(future.getTime() - (future.getTimezoneOffset() * 60000));
+  elements.expiry.value = local.toISOString().slice(0, 16);
+}
+
+elements.riskAcknowledgement.addEventListener('change', () => {
+  if (!elements.riskAcknowledgement.checked) {
+    clearFrozenReview('Risk acknowledgement cleared. Freeze and review the intent again.');
+  }
+  render();
+});
+elements.connectWallet.addEventListener('click', connectWallet);
+elements.switchNetwork.addEventListener('click', switchToArcTestnet);
+elements.freezeIntent.addEventListener('click', freezeIntent);
+elements.sendTransaction.addEventListener('click', requestOneTransaction);
+for (const input of [elements.recipient, elements.amount, elements.expiry, elements.memo, elements.confirmationPhrase, elements.finalSendConfirmation]) {
+  input.addEventListener('input', render);
+  input.addEventListener('change', render);
+}
+
+if (state.provider && typeof state.provider.on === 'function') {
+  state.provider.on('accountsChanged', (accounts) => {
+    state.account = Array.isArray(accounts) && isNonZeroAddress(accounts[0]) ? accounts[0] : '';
+    clearFrozenReview('Wallet account changed. Freeze and review the intent again.');
+    render();
+  });
+  state.provider.on('chainChanged', (chainIdHex) => {
+    state.chainIdHex = normalizeHex(chainIdHex);
+    clearFrozenReview('Wallet network changed. Freeze and review the intent again.');
+    render();
+  });
+}
+
+if (typeof window.addEventListener === 'function') {
+  window.addEventListener('beforeunload', (event) => {
+    if (state.transactionHash) {
+      event.preventDefault();
+      event.returnValue = 'A wallet transaction has been submitted and may still be pending. Leave anyway?';
+    }
+  });
+}
+
+setDefaultExpiry();
+render();

arc_builder_kit/examples/circle-wallet-integration/index.html

@@ -0,0 +1,155 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="description" content="Circle agent wallet integration lab for Arc Testnet — bootstrap, faucet, transfer, bridge, and Gateway walkthrough." />
+  <title>Circle Wallet Integration Lab · Arc MCP Builder Assistant</title>
+  <style>
+    :root { color-scheme: dark; --bg: #070916; --panel: rgba(255,255,255,.075); --line: rgba(255,255,255,.16); --text: #fbf9ff; --muted: #c6bedc; --accent: #7cf7d4; --violet: #b597ff; --warn: #ffd166; --good: #89ffb8; --circle: #00d4ff; }
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+    body { margin: 0; min-height: 100vh; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--text); line-height: 1.64; background: radial-gradient(circle at 12% 2%, rgba(0,212,255,.18), transparent 34rem), radial-gradient(circle at 90% 6%, rgba(124,247,212,.24), transparent 38rem), linear-gradient(180deg, #070916 0%, #121832 70%, #070916 100%); }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    a:focus-visible, button:focus-visible { outline: 3px solid var(--accent); outline-offset: 3px; }
+    .wrap { width: min(1160px, calc(100% - 32px)); margin: 0 auto; }
+    header { padding: 26px 0 12px; }
+    .topbar, nav, .actions { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+    .topbar { justify-content: space-between; }
+    .brand { color: var(--text); font-weight: 950; letter-spacing: -.02em; }
+    nav a, button, .badge { border: 1px solid var(--line); border-radius: 999px; padding: 10px 14px; background: rgba(255,255,255,.055); color: var(--text); font-weight: 850; }
+    button { cursor: pointer; }
+    button.primary { background: var(--circle); color: #06110f; border-color: transparent; }
+    .hero { display: grid; grid-template-columns: .95fr 1.05fr; gap: 18px; align-items: start; padding: 34px 0 22px; }
+    .layout { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; padding-bottom: 72px; align-items: start; }
+    .panel { border: 1px solid var(--line); border-radius: 28px; padding: clamp(20px, 4vw, 32px); background: linear-gradient(180deg, rgba(255,255,255,.1), var(--panel)); box-shadow: 0 22px 80px rgba(0,0,0,.34); }
+    .warning { border-color: rgba(255,209,102,.36); background: rgba(255,209,102,.08); }
+    .eyebrow { color: var(--circle); font-size: .78rem; letter-spacing: .16em; text-transform: uppercase; font-weight: 950; }
+    h1, h2, h3 { letter-spacing: -.035em; line-height: 1.08; }
+    h1 { margin: 12px 0 14px; font-size: clamp(2.15rem, 7vw, 4.6rem); }
+    h2 { margin-top: 0; font-size: clamp(1.35rem, 3vw, 2rem); }
+    p, li, label { color: var(--muted); }
+    .field { display: grid; gap: 8px; margin-bottom: 14px; }
+    input, select { width: 100%; border: 1px solid var(--line); border-radius: 16px; background: rgba(0,0,0,.24); color: var(--text); padding: 12px 14px; font: inherit; }
+    pre { white-space: pre-wrap; word-break: break-word; overflow-x: auto; border: 1px solid var(--line); border-radius: 18px; padding: 18px; background: rgba(0,0,0,.42); color: #eafff8; font-size: .82rem; }
+    .badge { display: inline-flex; width: fit-content; }
+    .badge.circle { color: var(--circle); border-color: rgba(0,212,255,.36); background: rgba(0,212,255,.08); }
+    .badge.good { color: var(--good); border-color: rgba(137,255,184,.36); background: rgba(137,255,184,.08); }
+    .badge.warn { color: var(--warn); border-color: rgba(255,209,102,.36); background: rgba(255,209,102,.08); }
+    .info-grid { display: grid; gap: 10px; }
+    .info-row { display: flex; justify-content: space-between; align-items: center; padding: 10px 14px; border: 1px solid var(--line); border-radius: 14px; background: rgba(0,0,0,.2); }
+    .info-label { color: var(--muted); font-size: .85rem; }
+    .info-value { color: var(--text); font-weight: 800; font-family: ui-monospace, "SF Mono", monospace; font-size: .85rem; }
+    .step-list { counter-reset: step; list-style: none; padding: 0; margin: 0; }
+    .step-list li { counter-increment: step; padding: 14px 0 14px 42px; position: relative; border-bottom: 1px solid var(--line); }
+    .step-list li:last-child { border-bottom: none; }
+    .step-list li::before { content: counter(step); position: absolute; left: 0; top: 14px; width: 28px; height: 28px; border-radius: 50%; background: var(--circle); color: #06110f; display: flex; align-items: center; justify-content: center; font-weight: 950; font-size: .82rem; }
+    code { font-family: ui-monospace, "SF Mono", monospace; font-size: .85rem; background: rgba(0,0,0,.3); padding: 2px 6px; border-radius: 6px; }
+    @media (max-width: 920px) { .hero, .layout { grid-template-columns: 1fr; } nav { display: none; } }
+    @media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
+  </style>
+</head>
+<body>
+  <a class="skip-link" href="#content" style="position:absolute;top:12px;left:-9999px;z-index:10;padding:10px 14px;border-radius:999px;background:var(--accent);color:#06110f;font-weight:950;">Skip to content</a>
+  <header class="wrap">
+    <div class="topbar">
+      <a class="brand" href="../../">Arc MCP Builder Assistant</a>
+      <nav aria-label="Circle wallet lab navigation">
+        <a href="../../">Home</a>
+        <a href="../../docs/view.html#circle-wallet-integration.md">Docs</a>
+        <a href="../arc-testnet-wallet-send-gate/">Wallet send gate</a>
+        <a href="../arc-agent-treasury-lab/">Treasury lab</a>
+        <a href="../x402-local-challenge-server/">x402 challenge</a>
+      </nav>
+    </div>
+  </header>
+  <main id="circle-wallet-lab" class="wrap">
+    <section class="hero">
+      <div>
+        <p class="eyebrow">Circle Agent Wallet · Arc Testnet</p>
+        <h1>Circle wallet integration lab</h1>
+        <p>Walk through the Circle agent wallet bootstrap flow on Arc Testnet: login, wallet creation, faucet funding, USDC transfer, and CCTP bridge — all through the <code>circle</code> CLI.</p>
+        <div class="actions">
+          <span class="badge circle" id="wallet-status">Session: not checked</span>
+          <span class="badge good" id="wallet-network">Arc Testnet · 5042002</span>
+        </div>
+      </div>
+      <div class="panel warning">
+        <h2>Safety boundary</h2>
+        <ul>
+          <li>No private keys in this page or repo — Circle CLI manages keys internally.</li>
+          <li>No custody, no mainnet, no autonomous spending.</li>
+          <li>Testnet USDC only — faucet tokens have no real value.</li>
+          <li>Human approval required for every wallet action.</li>
+          <li>Testnet only — faucet tokens have no real value.</li>
+          <li>x402 marketplace payments require mainnet USDC on an accepted chain.</li>
+        </ul>
+      </div>
+    </section>
+    <section class="layout">
+      <div class="panel">
+        <h2>Wallet state (read-only preview)</h2>
+        <p>This panel shows a static preview of the Circle wallet integration. It does not connect to Circle, RPC, or any external service. Use the <code>circle</code> CLI for live operations.</p>
+        <div class="info-grid">
+          <div class="info-row"><span class="info-label">Wallet address</span><span class="info-value" id="wallet-address">0x0cd9…a401</span></div>
+          <div class="info-row"><span class="info-label">Chain</span><span class="info-value">Arc Testnet</span></div>
+          <div class="info-row"><span class="info-label">Chain ID</span><span class="info-value">5042002 / 0x4cef52</span></div>
+          <div class="info-row"><span class="info-label">USDC ERC-20</span><span class="info-value" id="wallet-balance-erc20">— USDC</span></div>
+          <div class="info-row"><span class="info-label">USDC native (gas)</span><span class="info-value" id="wallet-balance-native">— USDC</span></div>
+          <div class="info-row"><span class="info-label">USDC contract</span><span class="info-value">0x3600…0000</span></div>
+          <div class="info-row"><span class="info-label">Gateway domain</span><span class="info-value">26 (Arc)</span></div>
+          <div class="info-row"><span class="info-label">Session</span><span class="info-value" id="wallet-session">testnet</span></div>
+        </div>
+        <div class="actions" style="margin-top:18px">
+          <button class="primary" id="refresh-preview">Refresh preview</button>
+          <button id="show-cli">Show CLI commands</button>
+        </div>
+      </div>
+      <div class="panel">
+        <h2>Bootstrap steps</h2>
+        <ol class="step-list">
+          <li><strong>Login (mainnet + testnet)</strong><br><code>circle wallet login &lt;email&gt; --type agent --init</code><br><code>circle wallet login &lt;email&gt; --type agent --testnet --init</code></li>
+          <li><strong>Create agent wallet</strong><br><code>circle wallet create --output json</code></li>
+          <li><strong>Fund via faucet</strong><br><code>circle wallet fund --address &lt;addr&gt; --chain "Arc Testnet" --token usdc</code></li>
+          <li><strong>Check balance</strong><br><code>circle wallet balance --address &lt;addr&gt; --chain "Arc Testnet"</code></li>
+          <li><strong>Transfer USDC</strong><br><code>circle wallet transfer &lt;to&gt; --amount 1 --address &lt;addr&gt; --chain "Arc Testnet"</code></li>
+          <li><strong>Bridge via CCTP</strong><br><code>circle bridge transfer "Base Sepolia" --amount 1 --address &lt;addr&gt; --chain "Arc Testnet"</code></li>
+        </ol>
+        <pre id="cli-output" style="display:none"># Login (mainnet)
+circle wallet login user@example.com --type agent --init
+# → OTP sent, then:
+circle wallet login --type agent --request &lt;id&gt; --otp &lt;code&gt;
+
+# Login (testnet — separate session)
+circle wallet login user@example.com --type agent --testnet --init
+circle wallet login --type agent --testnet --request &lt;id&gt; --otp &lt;code&gt;
+
+# Create wallet
+circle wallet create --output json
+
+# Fund from faucet
+circle wallet fund --address 0x0cd9… --chain "Arc Testnet" --token usdc
+
+# Balance
+circle wallet balance --address 0x0cd9… --chain "Arc Testnet" --output json
+
+# Transfer 1 USDC
+circle wallet transfer 0xrecipient… --amount 1 \
+  --address 0x0cd9… --chain "Arc Testnet" --output json
+
+# Bridge to Base Sepolia
+circle bridge transfer "Base Sepolia" --amount 1 \
+  --address 0x0cd9… --chain "Arc Testnet" --output json
+
+# Transaction history
+circle transaction list --address 0x0cd9… --chain "Arc Testnet"
+
+# Gateway balance
+circle gateway balance --address 0x0cd9… --chain "Arc Testnet"</pre>
+      </div>
+    </section>
+  </main>
+  <script src="./wallet-lab.js" defer></script>
+</body>
+</html>