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

Note: For the canonical endpoint directory with full request/response examples across all workers, see /docs/devops/api/endpoints.

All endpoints except GET /health require X-Internal-Auth-Key (fail-closed via createInternalAuthMiddleware).

A. Transfer tokens

• Endpoint: POST /transfer
• Headers: X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>
• JSON Payload:

  {'{'}
    "chain": "ethereum",
    "tokenAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "to": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
    "amount": "1000000000000000000"
  {'}'}
  

• Notes: amount is wei as a non-negative integer string. Zero-address recipients are rejected. Client valueUsd is ignored — USD notional is priced server-side (stablecoin / native oracle / DEX quote) and fail-closed if unpriceable.
• Success Response (200 OK):

  {'{'}
    "txHash": "0x53a9284739ebfd10482da73cbcfd10482da73cbcfd10482da73cbcfd10482ab",
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  {'}'}
  

---

B. Query Token Balance

• Endpoint: GET /balance?chain=polygon&address=0x…&token=0x…
• Headers: X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>
• Success Response (200 OK):

  {'{'}
    "chain": "polygon",
    "token": {'{'}
      "address": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
      "symbol": "USDT",
      "decimals": 6
    {'}'},
    "balance": "1485500000",
    "balanceFormatted": "1485.5"
  {'}'}
  

---

🛡️ 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. Keys are validated with /^0x?[0-9a-fA-F]{64}$/; mnemonics require 12–24 words. Wallet instances are cached under opaque keys (not the secret material). Error logs use toError(...).message only — never the secret value.
• Gas Price Limit Trap: Before signing /transfer, /approve, or /swap, the worker reads web3:max_gas_price_gwei from CONFIG_KV. If set to a positive number and current maxFeePerGas/gasPrice exceeds that gwei value, the request is forbidden (fail-closed). Unset / invalid → trap disabled. Fee-data read failures also block when the trap is enabled.
• USD value caps: Mutating routes enforce security.maxTransactionValueUsd using server-side pricing (resolveEnforcedValueUsd). High-value txs require confirmation when requireConfirmation is true (409 CONFIRMATION_REQUIRED).
• Whitelist: When whitelistedContractsOnly is true, destinations/tokens must be listed (DEX router addresses for the chain are auto-allowed for swaps).
• RPC safety: Provider URLs must be https (or http only for localhost/Anvil). Cloud metadata hosts and non-local http are rejected.
• Amount / address validation: Integer wei strings only; zero-address recipients and spenders rejected (native token zero-address still allowed as swap token sentinel).
• Isolate Access: All mutating calls require internal auth. Prefer Service Bindings over public exposure.

---

🔗 Next Steps

• trade-worker Profile — Review how execution orders route transactions to EVM wallet nodes.
• D1 Database Operations — Manage your SQLite schemas and sync positions logs.