Architecture
Separate pure math, settlement, policies, and off-chain routing.
Design. grapl uses concentrated liquidity in the initial core. A constant-product-only bootstrap is not the architecture baseline. Implementation coverage is tracked in status.
flowchart TB Client[Application or SDK] --> Core[grapl core] Adapter[Metis adapter] --> Quote[Snapshot and pure math] Router[Router - integration required] --> Core Core --> Math[Integer CLMM math] Core --> Positions[Positions and ticks] Core --> Fees[Fee liabilities] Core --> Hook[Pool hook - declared capabilities] Core --> Token[Token program and market vaults]
Responsibilities
| Layer | Responsibility | Must not assume |
|---|---|---|
| Math | Tick/price conversion, token deltas, rounding, swap steps, fee arithmetic | Account ownership or wallet authorization |
| Core program | Account checks, state transitions, solvency, user limits, settlement | That SDK validation protects direct callers |
| Hook interface | Typed, bounded policy requests and responses | Unrestricted access to vault authority |
| SDK | Safe inputs, account discovery, construction, user-facing output | A quote guarantees inclusion or execution |
| Metis adapter | Snapshot loading, contextual hook evaluation, deterministic quoting, account metas | That claimed quote identity authenticates a wallet or establishes router admission |
Markets own their state
The implementation gives each market its own vaults and accounting. A common program does not require a global mutable treasury touched by every swap. Shared configuration should be read-only on the swap path where possible.
Token A/B ordering is a technical identity. The launch's base and quote roles must be explicit. A token symbol or frontend label must never determine mint ordering.
Accounting precedes the vault balance
The spendable tokens in a vault can back principal, LP fees, protocol claims, beneficiary claims, and other identified allocations. Those amounts are not interchangeable. A direct transfer into a vault does not change the CLMM price.
Continue with fees, accounts, and invariants.