Docs

illaCode is autonomous code infrastructure. Developer tasks are routed to deterministic worker agents that read on-chain state through JSON-RPC, return structured results and emit an off-chain execution receipt — a keccak256 commitment over what was read, where, and when. Worker reputation is computed only from the recorded task history.

Nothing on the site is simulated. If an RPC does not answer you see RPC OFFLINE; if there is no history you see NO EXECUTIONS YET; if a worker has fewer than 5 finished tasks its score is INSUFFICIENT DATA.

Supported networks are EVM chains configured through environment variables. When a variable is empty a key-free public endpoint is used and the network is labelled “public RPC”.

NEXT_PUBLIC_ETH_RPC_URL=        # Ethereum (chain 1)
NEXT_PUBLIC_BASE_RPC_URL=       # Base (chain 8453)
NEXT_PUBLIC_ARBITRUM_RPC_URL=   # Arbitrum One (chain 42161)
NEXT_PUBLIC_CUSTOM_RPC_URL=     # optional extra EVM network
NEXT_PUBLIC_CUSTOM_CHAIN_ID=
NEXT_PUBLIC_CUSTOM_CHAIN_NAME=
NEXT_PUBLIC_DEFAULT_CHAIN=ethereum

Every RPC call runs through one timed wrapper (12 s timeout, one retry) that classifies failures into RPC_OFFLINE, RPC_TIMEOUT, RPC_RATE_LIMITED, METHOD_REVERTED, NO_RETURN_DATA or RPC_ERROR, and logs each request to rpc_requests. The nav badge probes every network with eth_blockNumber: ONLINE under 2.5 s, DEGRADED above, OFFLINE on failure.

A task moves QUEUED → RUNNING → SUCCESS | FAILED. Each transition is persisted with timestamps; durationMs is measured wall-clock on the server; rpcCalls counts RPC requests attributed to the task via async context.

Task {
  id, createdAt, updatedAt, type, network, chainId, target, input,
  status, startedAt, completedAt, durationMs, result, error,
  receiptHash, blockNumber, rpcCalls, agentId
}

Only view/pure functions are executable. Write functions in a supplied ABI are counted but rejected with INVALID_METHOD. Reads pin eth_call to the block number fetched immediately before, so the receipt commits to a consistent state.

A receipt is created for every successful task. It is an off-chain document — no transaction is sent and no gas is spent — and it must never be presented as an on-chain transaction. The receipt hash is deterministic: recompute it from the stored fields and it must match.

resultHash  = keccak256(utf8(canonicalJson(result)))
preimage    = canonicalJson({ v: "illacode-receipt-v1", receiptId, taskId, network, chainId, blockNumber, target, method, parameters, resultHash, timestamp, durationMs, agentId })
receiptHash = keccak256(utf8(preimage))

canonicalJson: keys sorted recursively, no whitespace, bigint → decimal string

POST /api/receipts/verify accepts a stored id/hash (recomputed from database rows) or a full receipt object (recomputed from the supplied fields, then cross-checked against the stored row). Change any committed field and the verdict becomes INVALID RECEIPT. Try it on any receipt page under “Tamper test”.

Agents are worker profiles with fixed routing (one worker per task type). Their statistics are recomputed on every request from task rows — nothing is cached or seeded.

score = 100 × ( 30% successRate
              + 20% reliability        // 1 − infrastructure failures / finished
              + 15% speed              // 1 at ≤400 ms avg, 0 at ≥6 s
              + 15% difficulty         // Σ difficulty(success) / Σ difficulty(finished)
              + 10% costEfficiency     // 1 at ≤2 RPC calls/success, 0 at ≥8
              + 10% recency )           // 1 now → 0 after 30 days idle

requires ≥ 5 finished tasks, otherwise INSUFFICIENT DATA

• ILLA-01 · Contract Inspector — CONTRACT_INSPECT, BYTECODE_READ
• ILLA-02 · ABI Reader — READ_FUNCTION
• ILLA-03 · Chain Observer — BLOCK_LOOKUP, ADDRESS_BALANCE
• ILLA-04 · Receipt Verifier — TOKEN_METADATA

All routes return { ok: true, data } or { ok: false, error: { code, title, message, detail } }. Bodies are validated with Zod. Rate limits are per client IP, per server instance.

GET  /api/health                     database + RPC health           (60/min)
GET  /api/network/status             live probe per network           (60/min)
GET  /api/block/latest?network=       latest block header              (30/min)
POST /api/tasks                      create + run a task              (20/min)
GET  /api/tasks?network&agentId&type&status&search&limit&offset
GET  /api/tasks/:id                  task + receipt + rpc log
GET  /api/agents                     registry with live stats
GET  /api/agents/:id                 profile, timeline, failures
POST /api/contract/inspect           { network, address, abi? }       (30/min)
POST /api/contract/call              { network, address, method, args, abi? }
POST /api/contract/token             { network, address }
GET  /api/receipts?search&agentId&network
GET  /api/receipts/:idOrHash         receipt + verification
POST /api/receipts/verify            { receiptId } | { receiptHash } | { receipt }

curl -X POST $APP/api/contract/call -H 'content-type: application/json' -d '{
  "network": "ethereum",
  "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "method": "symbol()(string)",
  "args": []
}'

help | chain | network <slug> | block [n] | inspect <addr> [abi]
balance <addr> | code <addr> | call <addr> <sig> [args…] | token <addr>
receipt <id|0xhash> | tasks | agents | clear

signature forms:  totalSupply()(uint256)
                  balanceOf(address)(uint256) 0xabc…
                  function ownerOf(uint256) view returns (address)

• No private keys or seed phrases anywhere; wallet connection is optional and used only as an address convenience.
• No write functions are exposed. Signatures without view/pure are executed as reads via eth_call; ABI write fragments are rejected.
• No eval, no user-supplied code execution, no shell. ABI JSON is parsed structurally; arguments are coerced per ABI type with range checks.
• Every RPC call has a 12 s timeout; every API route is rate-limited and validated; error strings are truncated.
• Rendered strings are React-escaped. Security headers: nosniff, frame SAMEORIGIN, strict referrer policy.

PostgreSQL via Prisma. Without DATABASE_URL the app runs on an in-process memory store and labels it everywhere as MEMORY STORE; with it, connection failures surface as DATABASE_UNAVAILABLE rather than silently degrading.

agents              id, name, specialization, description, taskTypes[], createdAt
tasks               lifecycle columns above; indexes on agent+createdAt, status, network, type, target
execution_receipts  one per successful task; indexes on receiptHash, agent+createdAt
rpc_requests        every timed RPC call: network, method, ok, durationMs, error, taskId
app_events          RECEIPT_VERIFY and other audit events

npm run db:push      # create tables (Supabase: use the pooled connection string)