mcp-opcode CLAUDE.md

engineering rules

The main claude code should use agents to write code and to audit code. The main claude code is only an orchestrator. Why? Agents do a better job and have fresh context and use more tokens giving better results. Otherwise main claude code frequently stops early and says, "thats all i can do in this session", or stuff like that, which NOBODY wants, we want the work to be done and correct. The orchestrator claude is to tell its children that they are children so that they don't spawn their own children.

THIS REPO

• THIS IS A CLIENT. IT TALKS TO A REMOTE HTTP API AND SIGNS PAYLOADS. IT HAS NO DATABASE, NO CHAIN CONNECTION AND NO SERVER STATE.
• NO EVM RPC. EVER. EVERY VALUE NEEDED TO BUILD A SIGNATURE COMES OFF THE QUOTE OR THE SESSION. IF SOMETHING SEEMS TO NEED A NODE, THE FIX IS FOR THE API TO CARRY THE FIELD, NOT FOR THE CLIENT TO OPEN A CONNECTION.
• SIGN-THEN-SUBMIT. prepare_X() RETURNS THE EXACT PAYLOAD TO SIGN, THE CALLER SIGNS IT WITH WHATEVER CUSTODY THEY HAVE, submit_X(prepared, sig) POSTS IT. THE CLIENT NEVER HOLDS A PRIVATE KEY AND NEVER SIGNS ON ITS OWN INITIATIVE.
• A SERVER-SUPPLIED ADDRESS IS NOT TRUSTED. CHAIN ID, GATEWAY AND DELEGATE ARE PINNED CLIENT-SIDE AND CHECKED AGAINST WHAT THE SERVER SENT BEFORE ANYTHING IS SIGNED. A COMPROMISED OR MITM'D BACKEND MUST NOT BE ABLE TO GET A SIGNATURE OVER AN ADDRESS OF ITS CHOOSING.
• REFUSE BEFORE YOU SIGN, NOT AFTER. EVERY GUARD RUNS BEFORE THE KEY IS TOUCHED. A SIGNATURE IS AN IRREVERSIBLE AUTHORISATION, A FAILED HTTP CALL IS NOT.
• DO NOT COMMIT KEYSTORES, PASSWORDS OR ANY ~/.opcode CONTENT. THE DEV KEYSTORE POINTER IS GITIGNORED AND STAYS THAT WAY.
• THIS REPO IS PUBLIC. NO INTERNAL FILE PATHS, NO BACKEND SOURCE CITATIONS, NO INFRA OR DEPLOY DETAIL, NO INTERNAL PLAN DOCS. WHEN A CONSTANT IS PINNED FROM A SERVER CONFIG, SAY WHAT IT MEANS AND THAT IT IS PINNED — NEVER WHERE IT CAME FROM.

Structure

• DON'T MIRROR A CONFIG STRUCT INTO A SECOND RUNTIME STRUCT, SIMPLY USE THE CONFIG STRUCT IN THE CODE DIRECTLY TO NOT DUPLICATE
• REPRESENT A FIXED SET OF CHOICES AS AN ENUM, NOT STRINGS, USE THE TYPESYSTEM
• WHEN MOVING CODE AROUND, DO NOT SHIM THINGS BY REEXPORTING THEM, IT CREATES A RETARDED SPAGHETTI OF DEPS AND IS LAZY
• DO NOT SHIM CODE WHEN REPLACING IT, FIX THE ENTIRE PATH
• NEVER FORMAT ERRORS TO STRINGS, HAVE FOR EACH FAILURE A CASE IN THE TYPE
• NEVER RETURN None TO MEAN FAILURE, RAISE THE TYPED EXCEPTION. Optional IS ONLY ALLOWED IF A VALUE CAN GENUINELY BE ABSENT AND ITS CORRECT OPERATION IF IT HAPPENS
• SERIALIZE U256 AS DECIMAL, ACCEPT DECIMAL OR HEX FOR DESERIALIZATION
• FOR ETHEREUM TYPES USE ACTUAL ETHEREUM TYPES, NOT BARE STRINGS OR LISTS OF INTS
• USE THE MODEL LAYER'S DERIVED (DE)SERIALIZATION, DON'T HAND-ROLL A PARSER