> For the complete documentation index, see [llms.txt](https://docs.armchain.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.armchain.org/account-abstraction/system-contracts.md). # System Contracts Armchain's AA functionality is built on a set of **system contracts** deployed at genesis. These contracts are embedded in the initial chain state and are available from block zero, similar to how the SFC (Special Fee Contract) governs validator staking and epoch management. ## Why System Contracts Native AA requires new EVM-level semantics: the node must be able to call into a validation contract before executing a transaction, handle paymaster logic, and route transactions through the AA pipeline. These behaviors are encoded in the client (go-opera / armchain-client) and backed by on-chain contracts that hold the authoritative logic. Deploying validation logic as protocol-level contracts (rather than user-deployed contracts) gives the following properties: * **Trust**: The network trusts these contracts implicitly, similar to how go-ethereum trusts precompile addresses * **Availability**: The contracts exist from genesis, no deployment transaction needed * **Upgradeability**: Changes can be made through governance rather than ad-hoc deployment ## Why Yul The AA system contracts are written in **Yul**, the EVM intermediate representation language (the same IR that `solc` compiles Solidity down to before generating bytecode). Armchain's native AA introduces new EVM opcodes that are not part of the standard Ethereum opcode set. These opcodes are required for the AA execution model (for example, opcodes that allow the protocol to invoke account validation and paymaster logic with the appropriate permissions and gas accounting). The Solidity compiler (`solc`) does not recognize these opcodes. Any contract that uses them must bypass the Solidity frontend and write directly in Yul. ``` ┌──────────────────────────────────────────────────┐ │ Standard Solidity contracts │ │ solc → Yul IR → EVM bytecode │ │ Works fine for regular contracts │ ├──────────────────────────────────────────────────┤ │ AA system contracts │ │ Yul (hand-written) → EVM bytecode │ │ Required because new opcodes are unrecognized │ │ by solc's opcode validation stage │ └──────────────────────────────────────────────────┘ ``` ### Implications for Developers If you are writing a **custom account validation contract** or a **custom paymaster**, and your contract uses the AA-specific opcodes, you must write that contract in Yul. There is no way to express these opcodes through the standard Solidity compiler today. Contracts that do **not** interact with AA-specific opcodes (for example, a paymaster that only checks a signature but delegates all AA calls to a trusted helper) can still be written in Solidity with appropriate care. > **Looking ahead**: The Armchain team is evaluating a fork of the Solidity compiler to add recognition of the new opcodes. Until that is available, Yul is the required path for any contract that touches AA-specific execution semantics. This is a known friction point and is being actively addressed. ## Deployed Contracts The following contracts are deployed at genesis as part of the AA system: ### Factory Registry The Factory Registry tracks approved account factory contracts and their trust levels. When a user deploys a new smart account (for example, a Guardian account or a Passkey account), the factory must be registered here for the deployment to be recognized by the AA mempool. The trust level system allows the protocol to distinguish between system-level factories (highest trust, deployed at genesis) and community-deployed factories (lower trust, subject to additional checks). ### Validation Scheme Contracts Each supported validation scheme has a corresponding system contract that implements the on-chain verification logic: | Contract | Scheme | Description | | --------------------- | ------------------ | ------------------------------------------------------ | | MLDSA Wallet | ML-DSA44 | Verifies ML-DSA44 signatures for AA accounts | | Passkey Wallet | P-256 / WebAuthn | Verifies P-256 signatures from WebAuthn authenticators | | SLH-DSA Wallet | SLH-DSA / SPHINCS+ | Verifies SLH-DSA hash-based signatures | | Guardian (MPC) Wallet | ECDSA via MPC | Verifies ECDSA signatures for MPC-managed accounts | | Hybrid Wallet | Combined | Supports combining multiple validation schemes | Each contract exposes a standard validation interface that the AA pipeline calls before allowing a transaction to execute. ### Foundation Paymaster The Foundation Paymaster system contract is pre-funded at genesis and handles gas sponsorship for new user onboarding. See [Paymaster](/account-abstraction/paymaster.md) for details on how it operates. ## Client Integration The system contracts are integrated into both the `geth` base client and the `opera` (armchain-client) consensus layer: * **geth layer**: State transition hooks call into the AA system contracts at the appropriate execution steps * **opera layer**: The AA mempool, gossip, and event inclusion logic is implemented here * **Tests**: Unit tests, integration tests, and end-to-end tests are in place covering the full AA transaction pipeline, from submission through validation, paymaster logic, and final execution ## Writing Custom Extensions Developers who want to add a new validation scheme to Armchain's AA framework should: 1. **Implement the validation interface in Yul**: The contract must expose the standard AA validation function with the correct ABI and use AA-specific opcodes for execution hooks. 2. **Register with the Factory Registry**: A factory contract must be deployed and registered before users can create accounts using the new scheme. 3. **Follow the staking requirements**: Custom paymasters associated with the scheme must stake ARM and maintain a deposit. 4. **Test against a local fakenet**: Spin up a local Armchain fakenet and run end-to-end tests before deploying to devnet. See [Fakenet](/node-operators/fakenet.md). The modular design means any validation scheme expressible in EVM bytecode can be added. The protocol does not constrain what the validation logic does, only that it conforms to the interface the AA pipeline calls. ## Further Reading * [Overview](/account-abstraction/overview.md): High-level AA architecture and transaction flow * [Validation Schemes](/account-abstraction/validation-schemes.md): Detailed descriptions of each supported scheme * [Paymaster](/account-abstraction/paymaster.md): Gas sponsorship and staking policy * [EVM Integration](/architecture/evm.md): EVM opcodes, precompiles, and Armchain extensions * [Fakenet](/node-operators/fakenet.md): Local development network for testing --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.armchain.org/account-abstraction/system-contracts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.