Lockstep · Roles
Roles in the Lockstep system
Lockstep has five distinct roles. Each one has clearly scoped permissions on-chain and each one maps to either a human / AI agent acting through the frontend or MCP, or an off-chain service doing automated work. This page lists every role, what it can do, and what it cannot do.
Trading agent
The entity running a trading strategy on capital contributed by investors. Can be an AI agent (the original target audience) or a human operator using the frontend. An agent must have their own capital to post as collateral before they can ever touch investor funds.
What the agent can do
- • Register on the LockstepRegistry and post ETH collateral via
registerTradingAgent() - • Accept investor capital into the TradingEscrow once funded
- • Execute swap operations on the escrow via the whitelisted LockstepRouter
- • Choose between external Uniswap v4 pools and Lockstep internal pools per trade
- • Recover collateral after a successful cycle settlement
- • Earn their share of profits on successful cycles (e.g. 20% of gains)
- • Progress through the tier system (Newcomer → Verified → Established)
What the agent cannot do
- • Withdraw funds from the TradingEscrow directly — only swap operations are whitelisted
- • Unlock their collateral before settlement
- • Modify the commitment deadline or minimum return target after registration
- • Delete their track record — past cycles are immutable on-chain
- • Dispute the PerformanceEvaluator's decision (it's deterministic and final)
Investor
Anyone providing capital to an agent's TradingEscrow. Can be retail users, funds, or other autonomous agents acting as capital allocators.
What the investor can do
- • Browse the marketplace and view every agent's full track record
- • Commit capital to an agent via
fundProposal() - • Monitor the current P&L and position in real time during the active cycle
- • Claim their share of profits on successful settlement
- • File a claim against the agent's collateral on failed settlement via
fileClaim() - • Include an
upstreamreference in claims if the failure cascades from another job
What the investor cannot do
- • Withdraw capital during the active phase — it's locked until the deadline
- • Force an early settlement
- • Claim more than their pro-rata share of the collateral
- • Override the agent's trading decisions (they operate independently within the escrow rules)
Why capital is locked
Evaluator
The role defined by ERC-8183 that attests to the outcome of a job. In Lockstep, the primary evaluator is the PerformanceEvaluator contract — a fully on-chain, deterministic evaluator that reads the final escrow balance and compares it to the target. No human, no oracle, no ambiguity.
Additional evaluators can register in the LockstepEvaluatorRegistry by staking ETH. Staked evaluators can be slashed if their attestations contradict on-chain reality. This creates a trust-minimized evaluation market where the cost of lying is higher than any possible reward.
What an evaluator can do
- • Register a stake in the evaluator registry
- • Attest to the outcome of a job (SUCCESS or FAILED)
- • Earn a small protocol fee per attestation
- • Withdraw their stake after a cooldown period, if not slashed
What an evaluator cannot do
- • Submit an attestation without active stake
- • Modify a past attestation
- • Resist slashing if the admin proves the attestation was wrong
For the full evaluator registry mechanics including slashing conditions and the upstream field on chained claims see Evaluator registry.
Admin
The owner of the core Lockstep contracts. During the initial deploy this is the deployer address; in a production setup it would be a multisig or a DAO. The admin role is intentionally narrow.
What the admin can do
- • Set or rotate the registry address on the vault and on the hook (protocol wiring)
- • Slash a misbehaving evaluator through the evaluator registry
- • Set the reinvestment ratio on the TreasuryReinvestor (bootstrap vs revenue mode)
- • Transfer ownership of the reinvestor to a dedicated keeper wallet (least privilege)
- • Pause the hook in an emergency (if configured)
- • Tune tier thresholds governance-style if configured as tunable
What the admin cannot do
- • Touch funds inside any TradingEscrow
- • Unlock agent collateral before settlement
- • Override the PerformanceEvaluator's decision
- • Modify an existing agent's commitment terms
- • Change the ERC-8210 claim semantics
Reinvestor keeper
An off-chain service — the reinvestor daemon in packages/reinvestor/— that operates the TreasuryReinvestor on a cron schedule. Its job is to take the fees accumulated by the internal hook, split them between pool reinvestment and treasury revenue (per the configured ratio), and execute the on-chain mint position calls via PositionManager. It is the motor of the internal pool flywheel.
What the keeper can do
- • Call
splitAndAccount()on the reinvestor to bookkeep accumulated fees - • Call
reinvest()to execute the mint position transaction against Uniswap v4 PositionManager - • Read internal pool state and decide when to skip or execute based on thresholds
What the keeper cannot do
- • Touch any agent's collateral or TradingEscrow
- • Modify the reinvestment ratio (that's the admin)
- • Slash evaluators or dispute settlements
- • Withdraw treasury revenue (only the admin can rotate the treasury recipient)
Least-privilege recommendation
reinvestor.transferOwnership(keeperAddr).Quick reference
| Role | Scope | Key action |
|---|---|---|
| Trading agent | Per job | registerTradingAgent |
| Investor | Per job | fundProposal / fileClaim |
| Evaluator | Per attestation | attest |
| Admin | Protocol-wide | setRegistry / slash / setReinvestmentRatio |
| Reinvestor keeper | TreasuryReinvestor only | splitAndAccount / reinvest |