The protocol in one document.

ORCHN is a fixed-supply ERC-20 paired with WETH in a single Uniswap V4 pool. The pool is gated by a custom hook that does three things on every swap: takes 3% of the ETH leg as a fee, enforces a per-transaction sell cap, and emits a typed Signal event.

The 3% fee is routed in real time to three independent staking pools — Pulse, Thesis, Sentinel — each with its own lock period, fee share, and protocol role. Holders choose a tier by staking ORCH into it.

The sell cap is the only governance-mutable parameter. It is tuned by Thesis stakers via a lightweight single-purpose governor.

AgentOrchestrationHook.sol inherits a self-rolled BaseHook (v4-periphery 4.0.0 dropped the upstream helper). Its permission mask is BEFORE_SWAP | AFTER_SWAP | BEFORE_SWAP_RETURNS_DELTA = 0x40C0. The hook address must be mined via HookMiner until the lower 14 bits match.

beforeSwap detects direction (buy or sell) from zeroForOne and the currency layout, computes the ORCH amount being moved, reverts if a sell exceeds the cap, and returns a BeforeSwapDelta that captures the 3% ETH fee out of the trade. The captured ETH is forwarded atomically to AgentStaking.notifyReward.

afterSwap emits Signal(uint64 ts, address trader, int256 amount0Delta, int256 amount1Delta, uint8 kind). kind ∈ {0=BUY, 1=SELL, 2=SELL_CAP_HIT}. No state mutation happens in afterSwap — it exists only to give indexers a reliable event surface.

Each tier runs an independent Synthetix-style reward accumulator. Stake ORCH, accumulate ETH rewardPerToken, claim or unstake when the lock allows.

Pulse has zero lock: lockEndsAt is always set to block.timestamp, so unstake is permissioned only by sufficient balance. Thesis adds 3 days; Sentinel adds 14 days. Adding stake extends the user's lock to the new max — this prevents games where you stake just before claiming to dilute existing stakers.

If a tier has zero stake when a reward arrives, its slice is parked in unallocated[tier] and flushed on the next non-zero notifyReward. This avoids stuck ETH (a problem we hit in an earlier project, uSTAKE).

Bootstrap: AgentStaking is funded with 100,000 ORCH at deploy. The first 50k of cumulative Sentinel stake gets paid pro-rata from this bootstrap pool. Any residual stays in the contract and continues to back future redistribution.

ThesisGovernor.sol is a single-purpose contract: it can only adjust sellCapBps on the hook, and only Thesis stakers can vote. Proposals are aligned to 7-day epochs anchored at deploy time.

Anyone with Thesis stake can call propose(uint16 newSellCapBps) with a 0.001 ETH bond. newSellCapBps must be in [25, 200]. Voters call vote(proposalId, support) with weight equal to their current Thesis stake.

After the epoch closes, anyone may call execute(proposalId). If yesVotes >= 5% of total Thesis stake at execution time, the hook's sellCapBps updates. The proposer's bond is refunded on quorum-met, or forfeited to the Sentinel pool on quorum-fail.

There is no admin role, no veto, no upgrade path. The hook's setSellCapBps function is callable only by the governor address fixed at deploy.

The pool is initialized with 700,000 ORCH and 0 ETH. All token liquidity is concentrated in a tick range above the initial spot price, so the pool can sell ORCH into ETH as price climbs, but the deployer never seeds the ETH side.

This is the same single-side pattern used in prior projects (HookPeg v3, uPEP, uBEAST). Deployment uses PositionManager.multicall with the initializePool and modifyLiquidities calls bundled, and approves ORCH through Permit2 first.

The initial sqrtPriceX96 is computed off-chain and verified in Python before broadcast — past projects have shipped with a mis-computed price (uSTAKE, HOOKCAST) and the result was a pool floor multiple orders of magnitude off. The deploy script aborts unless the computed price matches the expected mcap within 1%.

The LP NFT is held by the deployer EOA and is not time-locked at launch. This matches the user's posture on prior projects.

Every swap on the pool fires a Signal event from the hook's afterSwap callback. Events are typed: kind 0 (BUY), 1 (SELL), 2 (SELL_CAP_HIT). The Signal feed is the canonical public record of protocol activity.

A thin indexer (planned to live in orchn-state/) reads these logs and serves them via a static JSON endpoint that the /signals page consumes. The indexer holds no privileged state — anyone can rebuild it from chain in an afternoon.

Additional events emitted by the staking and governor contracts (Staked, Unstaked, Claimed, ProposalCreated, Voted, Executed) supplement the Signal feed for the live activity stream.

First-staker bootstrap capture. The 100k bootstrap pool is paid against the first 50k of Sentinel stake. A single early staker can capture a meaningful share. We accept this as a first-mover incentive and bound the exposure by capping the eligible window.

Live-balance voting weight, no snapshot. Vote weight is computed at vote time, not at proposal creation. With a 3-day Thesis lock and a 7-day epoch, flash-stake-and-dump within an epoch is bounded but not impossible. v2 may add Merkle snapshots.

LP not locked at launch. The deployer keeps the LP NFT removable. This is a deliberate posture, not an oversight — locking can be added later via Sablier or a vesting contract.

Deployer keeps 20% supply. This is held by an EOA, not a multisig in v1. Buyers should treat this as a known centralization risk that may unwind over time.

sqrtPriceX96 miscomputation at deploy — mitigated by mandatory Python reproduction before broadcast.

HookMiner failing to find a salt within 2M iterations — mitigated by fallback to an alternate permission mask with documented impact.

sellCapBps voted too low and starving liquidity — mitigated by hard floor of 25 bps inside setSellCapBps.

Reward ETH stuck in a tier with zero stake — mitigated by explicit unallocated[tier] storage and on-next-notify flush.

Same-day abort pattern from prior launches — design assumes the user proceeds; if aborted, single-side LP is removable via PositionManager and the staking/governor contracts remain inert and harmless on-chain.