Hoox Docs

🌐 web3-wallet-worker Isolate Profile

The web3-wallet-worker is the on-chain gateway of the Hoox trading ecosystem. Running as an isolated private micro-worker, this service is responsible for securely managing EVM mnemonics and private keys (bound as encrypted Workers Secrets), querying multi-chain gas limits and token balances, executing native/ERC-20 transfers, and signing smart contract swap payloads (e.g. Uniswap/1inch routers) via JSON-RPC providers.

⚡ 1. Declared Wrangler Configurations & Bindings

The web3-wallet-worker does not expose a public URL, communicating internally via V8 Service Bindings. Its wrangler.jsonc specifies:

{
  "name": "web3-wallet-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-19",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "vars": {
    "DEFAULT_CHAIN": "ethereum",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "secrets": [
    "INTERNAL_KEY_BINDING",
    "WALLET_MNEMONIC_SECRET",
    "WALLET_PK_SECRET",
    "RPC_PROVIDER_URL",
  ],
}

🔑 2. Environmental Variables & Encrypted Secrets

  • WALLET_PK_SECRET: Encrypted private key used for single-account execution.
  • WALLET_MNEMONIC_SECRET: Encrypted 12 or 24-word HD wallet seed phrase used to derive multiple accounts.
  • RPC_PROVIDER_URL: High-availability HTTP Ethereum / EVM RPC provider (e.g., Infura, Alchemy, or QuickNode).
  • INTERNAL_KEY_BINDING: Shared key used to validate calls from internal compute nodes.

Local Development Mocking (.dev.vars)

WALLET_PK_SECRET=0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
WALLET_MNEMONIC_SECRET="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
RPC_PROVIDER_URL=http://localhost:8545
INTERNAL_KEY_BINDING=dev_shared_internal_security_key

🔌 3. Internal REST API Specification

A. Execute On-Chain Transaction

  • Endpoint: /process
  • Method: POST
  • Headers: X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>
  • JSON Payload: 
    {
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "action": "sendTransaction",
    "chain": "arbitrum",
    "to": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "value": "0.05",
    "data": "0xa9059cbb000000000000000000000000...",
    "gasLimit": 100000
  }
}
  • Success Response (200 OK): 
    {
  "success": true,
  "result": {
    "txHash": "0x53a9284739ebfd10482da73cbcfd10482da73cbcfd10482da73cbcfd10482ab",
    "nonce": 142,
    "gasUsed": 64205,
    "effectiveGasPrice": "24000000000"
  },
  "error": null
}

B. Query Token Balance

  • Endpoint: /process
  • Method: POST
  • JSON Payload: 
    {
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "action": "getBalance",
    "chain": "polygon",
    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "tokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f"
  }
}
  • Success Response (200 OK): 
    {
  "success": true,
  "result": {
    "balance": "1485.50",
    "symbol": "USDT",
    "decimals": 6
  },
  "error": null
}

🛡️ 4. On-Chain Security Best Practices

Operating hot wallets on public blockchain networks introduces extreme security vectors:

  • Harden Private Keys: Never write keys to wrangler config files or print them in telemetry logs. Always provision keys via encrypted Cloudflare Secrets.
  • Gas Price Limit Traps: To prevent severe loss during network congestion or flash crashes, the worker enforces a gas limit trap—if current network gas price exceeds your KV configured limit (web3:max_gas_price_gwei), transactions are dropped before signing to prevent massive fee consumption.
  • Isolate Access: All calls must originate internally via Service Bindings. The wallet worker does not bind to public ports, meaning external scrapers cannot send raw transaction payloads or try to brute-force auth codes.

Tip: Testing on-chain logic locally? Use the Docker runtime stack (hoox dev start --runtime docker) to launch an isolated Hardhat/Anvil node container and test private wallet swaps on a simulated local EVM fork safely!

🔗 Next Steps