# WEALD Knowledge Base

> A complete product, protocol, engineering, security, integration, and operations guide

**Document status:** Living technical reference
**Network focus:** Robinhood Chain mainnet (`4663`) and testnet (`46630`)
**Protocol status:** Mainnet application, V3 creation, and keeper live; manual validation remains ongoing
**Last source review:** 2026-09-01
**Repository:** `vincenzofamoso/weald`

---

## Table of contents

1. [WEALD in one minute](#1-weald-in-one-minute)
2. [The problem WEALD solves](#2-the-problem-weald-solves)
3. [Core concepts from zero](#3-core-concepts-from-zero)
4. [Product capabilities](#4-product-capabilities)
5. [Detailed use cases](#5-detailed-use-cases)
6. [End-to-end user journeys](#6-end-to-end-user-journeys)
7. [System architecture](#7-system-architecture)
8. [Smart-contract architecture](#8-smart-contract-architecture)
9. [Grove mechanics](#9-grove-mechanics)
10. [Auto-close mechanics](#10-auto-close-mechanics)
11. [Pool creation and liquidity bootstrapping](#11-pool-creation-and-liquidity-bootstrapping)
12. [Fees and worked examples](#12-fees-and-worked-examples)
13. [Web application](#13-web-application)
14. [Pool discovery and market data](#14-pool-discovery-and-market-data)
15. [Indexer, database, and API](#15-indexer-database-and-api)
16. [SDK and integration model](#16-sdk-and-integration-model)
17. [Keeper service](#17-keeper-service)
18. [Security model](#18-security-model)
19. [Roles, governance, and emergency controls](#19-roles-governance-and-emergency-controls)
20. [Token compatibility](#20-token-compatibility)
21. [Deployment provenance and live addresses](#21-deployment-provenance-and-live-addresses)
22. [Repository and technology stack](#22-repository-and-technology-stack)
23. [Local development](#23-local-development)
24. [Testing and verification](#24-testing-and-verification)
25. [Production operations](#25-production-operations)
26. [Monitoring and incident response](#26-monitoring-and-incident-response)
27. [Recovery and protocol independence](#27-recovery-and-protocol-independence)
28. [Current limits and roadmap boundaries](#28-current-limits-and-roadmap-boundaries)
29. [Troubleshooting](#29-troubleshooting)
30. [Glossary](#30-glossary)
31. [Source map](#31-source-map)

---

## 1. WEALD in one minute

WEALD is an independent liquidity application for Robinhood Chain. It helps a user discover verified markets, create a concentrated-liquidity position, keep the resulting Uniswap V3 NFT in their own wallet, and optionally authorize an on-chain rule that closes the position after a target price has been sustained.

> **Core compatibility promise:** Every live WEALD LP is a 100% standard Uniswap V3 position NFT minted by the official position manager. It is not a WEALD wrapper, vault share, or custodial receipt. The owner can manage it through WEALD, compatible Uniswap V3 tooling, or direct verified contract calls even if WEALD is unavailable. Compatible PONS-launched ERC-20 tokens can be paired against any other valid Robinhood Chain ERC-20 through WEALD's canonical V3 pool-creation flow; this does not imply current management of PONS V4 LP positions.

The central product object is a **Grove**. A Grove is a standard Uniswap V3 position NFT created through extra safeguards. A single-sided Grove starts with one token and places that token in a price range entirely above or below the current pool price. As the market moves through the range, the AMM progressively converts the position into the other token.

The optional auto-close service adds a user-defined exit condition. The owner specifies a TWAP confirmation period, an expiry, and a minimum net output. The NFT remains in the owner’s wallet. The owner grants a revocable NFT approval to the auto-closer. After both spot and time-weighted price cross the range boundary, any executor can close the position. Settlement happens atomically, sending the owner proceeds and splitting the disclosed fee.

WEALD uses the official Robinhood Chain Uniswap V3 deployment. Its mainnet Groves are ordinary position-manager NFTs. Users retain a direct recovery path through standard Uniswap tooling and verified explorer calls.

WEALD currently has:

- live mainnet pool discovery;
- single-sided Grove creation;
- direct position inspection and management;
- opt-in, revocable, TWAP-confirmed auto-close rules;
- new V3 pair creation with initial two-sided liquidity;
- a permissionless keeper implementation;
- an unsigned TypeScript SDK;
- an event indexer and derived API foundation;
- deployment manifests, verification scripts, security evidence, monitoring examples, and operational runbooks.

WEALD does not currently issue a protocol token. Vault custody, liquidity mining, public V4 writes, and fabricated analytics stay outside the live product boundary.

WEALD is third-party software. It is not affiliated with Robinhood or Uniswap.

## 2. The problem WEALD solves

Concentrated liquidity is capital-efficient because liquidity can be assigned to a chosen price interval. The same flexibility creates practical friction:

- users must understand token order, ticks, fee tiers, range placement, approvals, and minimum amounts;
- an incorrectly placed range can require two assets or become immediately inactive;
- pool addresses and token symbols can be spoofed;
- LP positions require active monitoring when they are used as range orders;
- automation often introduces custody, opaque bots, or broad approvals;
- indexers, RPCs, market-data services, and interfaces can disagree;
- liquidity recovery must remain possible if an application disappears.

WEALD turns those concerns into explicit product boundaries. It validates pool identity against the canonical factory, computes bounded ranges, mints the NFT directly to the chosen recipient, uses exact approvals, snapshots auto-close terms on-chain, confirms exits with spot and TWAP observations, and preserves direct ownership.

The protocol is designed around a simple principle: the chain owns the truth, the wallet owns the position, and off-chain services improve usability without becoming a custody layer.

## 3. Core concepts from zero

### 3.1 Automated market maker

An automated market maker, or AMM, holds two assets in a pool and quotes trades from a mathematical relationship between its reserves and liquidity. Traders swap against the pool. Liquidity providers earn a share of swap fees while taking market and inventory risk.

### 3.2 Concentrated liquidity

Uniswap V3 allows liquidity to be placed between a lower and upper price. Capital works only while the market is within that interval. A narrower range can earn more fees per unit of capital while increasing the chance that price leaves the range.

### 3.3 Token order

Every V3 pool has `token0` and `token1`. Their order comes from address sorting. Human labels such as “AAPL/USDG” do not determine contract order. Price calculations, tick direction, minimum amounts, and single-sided placement must use canonical address order.

### 3.4 Ticks

V3 represents price on a logarithmic tick scale. Adjacent ticks differ by a factor of `1.0001`. Each fee tier has a tick spacing, and usable boundaries must align to that spacing.

### 3.5 Fee tier

A pair can have separate pools at multiple swap fee tiers. WEALD exposes the standard V3 choices used by its interface:

- `0.05%` for closely related or highly efficient markets;
- `0.30%` as a common general-purpose tier;
- `1.00%` for volatile or thin markets.

Different fee-tier pools have distinct addresses, liquidity, prices, and activity.

### 3.6 Position NFT

A V3 liquidity position is represented by an ERC-721 NFT in the canonical Nonfungible Position Manager. The NFT records pool identity, tick bounds, liquidity, and accrued fee accounting. Whoever owns it controls the position.

### 3.7 Grove

A Grove is WEALD’s guarded creation and management experience around a standard V3 NFT. The term describes the workflow and safety constraints. It does not replace the underlying Uniswap ownership model.

### 3.8 Single-sided range

A position can begin with only `token0` when its entire range is above the current tick. It can begin with only `token1` when its entire range is at or below the current tick. The exact orientation follows V3 math and address order.

As price crosses a one-sided range, the position’s inventory changes. This makes a Grove useful as an on-chain range order, with the important difference that conversion happens continuously throughout the interval.

### 3.9 Spot tick and TWAP tick

The spot tick is the pool’s current tick. A time-weighted average price, or TWAP, averages observed ticks across a selected window. Requiring both spot and TWAP past a boundary makes a brief price spike insufficient for auto-close eligibility.

### 3.10 Permissionless execution

An auto-close rule can be executed by any address once its contract conditions pass. The keeper is a convenience service. It has no exclusive role. This keeps correctness in the contract and availability in an open executor model.

## 4. Product capabilities

### 4.1 Discover verified markets

Users can search by token, symbol, quote asset, token contract, or pool contract. Discovery merges multiple candidate sources, then checks candidates on-chain against the pinned canonical Uniswap factory. A third-party listing cannot make an unrelated pool writable through WEALD.

Markets can be ranked by trending activity, establishment, fees, recency, and PONS provenance. Quote-asset filters narrow the view. Live pool state includes current tick, fee tier, tokens, and verified pool identity.

### 4.2 Create a single-sided Grove

The user chooses a pool, input token, amount, target movement, range parameters, and protection settings. WEALD constructs an exact approval and a `createGrove` call. The contract checks:

- deadline;
- emergency pause state;
- recipient and token addresses;
- canonical pool existence and initialization;
- tick alignment and configured width bounds;
- deviation between expected and live tick;
- the range’s single-sided orientation;
- exact token receipt, rejecting transfer-tax behavior;
- minimum amount used and minimum liquidity.

The resulting NFT is minted directly to the recipient. Unused net input returns to the caller. The creation fee goes directly to the configured recipient. Temporary token allowance to the position manager is cleared.

### 4.3 Inspect and manage a position

The application can read NFT owner, tokens, fee tier, ticks, liquidity, approvals, live pool state, and registered automation. Standard management paths include fee collection, partial liquidity removal, full close, approval changes, and NFT transfer.

### 4.4 Register an auto-close rule

The current NFT owner approves the auto-closer for one position and registers a rule. The rule records:

- owner;
- canonical pool;
- tick bounds;
- close direction;
- TWAP duration;
- expiry;
- minimum net output;
- auto-close fee rate;
- keeper share;
- fee recipient.

Fee terms are snapshotted when the rule is created. A later fee-controller update does not silently rewrite an active rule.

### 4.5 Cancel automation

The recorded owner may cancel an active rule. Revoking NFT approval also prevents execution. Direct management of the NFT through compatible Uniswap V3 tooling remains available.

### 4.6 Execute an eligible exit

After the rule boundary is crossed by both spot and TWAP, any executor may call `execute`. The contract verifies ownership, approval, position identity, range, liquidity, expiry, and output protection. It removes all liquidity, collects tokens, burns the empty NFT, pays net proceeds to the owner, and distributes fee shares within one atomic transaction.

### 4.7 Create a new V3 market

The pool bootstrapper atomically creates a canonical V3 pool, initializes its starting price, and mints its first two-sided position. Both token amounts are pulled exactly. Initial tick must lie within the seeded range. The NFT goes directly to the chosen recipient. Fees and refunds settle in the same transaction.

The current bootstrapper rejects a pool that already exists. Adding liquidity to an existing pool follows the standard position-manager path in the application rather than the bootstrap function.

### 4.8 Integrate through unsigned tooling

The SDK builds and validates calls without accepting private keys. It supplies helpers for manifests, approvals, pool creation, Grove creation, auto-close rules, position management, price-to-`sqrtPriceX96` conversion, range calculation, fee math, base-unit conversion, and minimum-output estimates.

## 5. Detailed use cases

### 5.1 Token holder sets a staged exit

Mira holds a token that trades against USDG. She expects price to rise and wants to convert her token into USDG across a 20% interval.

1. Mira opens Pools and verifies the token/USDG market.
2. She creates a Grove with her token as the sole input.
3. WEALD places the range on the correct side of the live tick.
4. Her NFT arrives in her wallet.
5. She registers an auto-close rule with a sustained TWAP window, expiry, and minimum output.
6. As the price advances through the range, V3 converts inventory toward USDG.
7. After price clears the final boundary long enough, the keeper executes.
8. Net proceeds arrive directly in Mira’s wallet.

This flow behaves like a gradual range order. It includes LP economics, price-path effects, fees, MEV risk, and possible inactivity if the target is never reached.

### 5.2 Treasury creates transparent market liquidity

A project treasury wants an on-chain market for its token against WETH.

1. The treasury chooses a V3 fee tier and a starting human-readable price.
2. The SDK converts that price using token decimals and canonical address order.
3. The treasury reviews token amounts, minimums, full-range ticks, creation fee, and recipient.
4. It sends exact approvals.
5. The bootstrap transaction creates and initializes the canonical pool and seeds liquidity.
6. The treasury receives the standard LP NFT.

The creator defines the initial price. Arbitrage can move an inaccurate price immediately. The treasury should determine a defensible price and understand the capital efficiency of its chosen range.

### 5.3 Existing LP adds a guarded automation rule

An LP already owns a compatible one-sided V3 NFT. They open Positions, inspect its live state, approve the auto-closer for that NFT, and register a bounded rule. The rule is valid only while ownership, pool identity, ticks, liquidity, approval, expiry, and price conditions remain consistent.

### 5.4 User recovers without the WEALD interface

If the web app is unavailable, the NFT owner can use the verified Nonfungible Position Manager on the block explorer or a compatible V3 interface. They can collect fees, decrease liquidity, transfer the NFT, revoke an approval, and burn an empty position. The repository also includes a recovery script.

### 5.5 Independent keeper executes a rule

An operator can run the open-source keeper or build another executor. The service reconstructs active rules from confirmed events, simulates each eligible execution, applies gas limits, submits a transaction, waits for confirmation, and updates its checkpoint. No keeper role is required.

### 5.6 Wallet or portfolio app integrates WEALD

A wallet can import the ABI and SDK packages, validate the signed deployment manifest, read a user’s V3 NFTs, show WEALD automation state, and build unsigned calls. The wallet remains responsible for user confirmation and signing.

### 5.7 Researcher reconstructs protocol state

An analyst can replay canonical factory events and WEALD contract events from deployment blocks. The indexer stores checkpoints, pool records, and raw event payloads. Because API data is derived, the chain remains the authoritative source.

## 6. End-to-end user journeys

### 6.1 Discover to Grove

```text
Search token or pool
        ↓
Collect candidate markets
        ↓
Verify pool against canonical factory
        ↓
Read live tick, spacing, tokens, and fee
        ↓
Choose input, amount, target, and protections
        ↓
Approve exact ERC-20 amount
        ↓
Create Grove
        ↓
Receive standard V3 NFT directly
```

### 6.2 Grove to automated exit

```text
Inspect owned NFT
        ↓
Calculate boundary and expected crossed output
        ↓
Approve the auto-closer for this NFT
        ↓
Register TWAP, expiry, and minimum net output
        ↓
Keeper rebuilds active rule from confirmed event
        ↓
Spot and TWAP cross boundary
        ↓
Simulation succeeds within gas policy
        ↓
Atomic decrease → collect → burn → distribute
```

### 6.3 New market

```text
Enter two token addresses
        ↓
Select fee tier and human starting price
        ↓
Resolve token order and decimals
        ↓
Compute sqrtPriceX96 and aligned range
        ↓
Approve exact amounts
        ↓
Create + initialize pool + mint first NFT atomically
        ↓
Receive refunds and position NFT
```

## 7. System architecture

WEALD separates immutable settlement from replaceable infrastructure.

```mermaid
flowchart TB
  U[User wallet] --> W[Next.js web app]
  I[Integrator] --> S[Unsigned TypeScript SDK]
  W --> S
  S --> C[WEALD periphery contracts]
  U --> C
  C --> V3[Official Uniswap V3 contracts]
  V3 --> NFT[User-owned LP NFT]

  F[Canonical factory events] --> X[Reorg-aware indexer]
  C --> X
  X --> DB[(PostgreSQL)]
  DB --> A[Fastify API]
  A --> W

  K[Permissionless keeper] --> C
  K --> RPC[Robinhood Chain RPC]
  W --> RPC
  X --> RPC

  M[Append-only manifests] --> S
  M --> W
  M --> O[Operations and verification]
```

### 7.1 Boundary 1: upstream AMM core

The official V3 factory, pools, position manager, router, quoter, WETH, and multicall provide AMM settlement and standard NFT ownership. WEALD does not fork or modify their mainnet behavior.

### 7.2 Boundary 2: WEALD periphery

Immutable periphery contracts add guarded creation, bounded fees, emergency creation pauses, manifest provenance, read helpers, automation registration, and atomic close settlement.

### 7.3 Boundary 3: unsigned clients

The web app and SDK calculate parameters and construct calls. They hold no signing authority. Wallet software shows and signs transactions.

### 7.4 Boundary 4: derived services

The indexer, database, API, charts, and market metadata make the product easier to browse. Their records can be rebuilt from chain data and cannot change NFT ownership.

### 7.5 Boundary 5: operational automation

The keeper pays gas to execute rules that already satisfy on-chain conditions. It has no privileged protocol role and cannot redirect owner proceeds.

## 8. Smart-contract architecture

### 8.1 `WealdFactory`

The factory is a constrained entry point around canonical V3 pool creation. It pins the upstream factory relationship and emits WEALD-readable creation provenance. Pool identity ultimately comes from the canonical factory.

### 8.2 `SingleSidedGroveManagerV2`

This contract creates guarded one-token positions. Its immutable dependencies are the V3 factory, position manager, emergency guardian, fee controller, and minimum/maximum width in tick spacings.

Key call:

```solidity
createGrove(CreateGroveParams)
```

The parameter structure covers token pair, input token, fee tier, lower and upper ticks, expected tick, maximum deviation, amount, minimum used amount, minimum liquidity, recipient, and deadline.

Important events:

- `SingleSidedGroveCreated`
- `GroveCreationFeePaid`

V2 adds the active fee-controller model while preserving direct NFT ownership and exact balance checks.

### 8.3 `GroveAutoCloserV2`

This contract stores and executes opt-in rules. It validates the current owner and approval at registration and execution. It snapshots fee settings. Each rule is bound to pool identity and original tick range.

Key calls:

```solidity
register(uint256 positionId, uint32 twapSeconds, uint256 minimumOutput, uint64 expiresAt)
cancel(uint256 positionId)
execute(uint256 positionId)
rules(uint256 positionId)
```

Important events:

- `AutoCloseRegistered`
- `AutoCloseCancelled`
- `AutoCloseExecuted`

Execution deletes the rule before external settlement operations, then relies on atomic transaction rollback if a later requirement fails.

### 8.4 `GroveFeeController`

The current fee controller manages:

- creation fee basis points;
- auto-close fee basis points;
- keeper share basis points;
- fee recipient;
- delayed configuration changes.

Fee caps are enforced on-chain. Active auto-close rules preserve their registered terms.

### 8.5 `TwoSidedPoolBootstrapper`

The bootstrapper creates a previously absent canonical V3 pool and seeds its first active two-token position in one transaction. It rejects identical or zero addresses, zero amounts, expired deadlines, paused creation, an existing pool, invalid ticks, an initial price outside the range, fee-on-transfer behavior, zero net amounts, and insufficient liquidity.

Important events:

- `PoolBootstrapped`
- `BootstrapCreationFeePaid`

### 8.6 `WealdAccessManager`

The access manager defines delayed administrative paths and role boundaries. It is part of deployment provenance and security posture. Immutable settlement modules do not become upgradeable through this contract.

### 8.7 `WealdEmergencyGuardian`

The guardian exposes operation-specific pause bits. The Grove creation path checks the bit assigned to single-sided creation. Emergency control is scoped to defined WEALD entry points. It does not seize user NFTs or pause canonical V3 itself.

### 8.8 `WealdDeploymentRegistry`

The registry records contract and deployment identity for clients and operators. Append-only off-chain manifests add source commit, compiler, bytecode hashes, verification state, roles, and smoke-test evidence.

### 8.9 `WealdLens`

The lens groups read-only protocol and position data for clients. It improves read ergonomics without holding authority.

### 8.10 Supporting modules

- `WealdPositionDescriptor` supplies metadata-oriented position descriptions.
- `WrappedNativeAdapter` handles explicit native-token wrapping boundaries.
- `WealdRoles` centralizes role identifiers.
- V1 manager, auto-closer, and historical fee controller remain documented as deployed history.
- PONS V4 manager and auto-closer code represent a separate integration track. Public V4 Grove writes remain outside the active mainnet manifest until their release gates pass.

### 8.11 Immutability and versioning

WEALD Phase 1 uses immutable modules instead of proxies. A protocol change is released as a new contract and manifest entry. Existing NFTs remain standard upstream NFTs. Existing auto-close rules remain governed by the contract where they were registered.

## 9. Grove mechanics

### 9.1 Range direction

For a `token0`-only Grove, the live tick must be below `tickLower`. For a `token1`-only Grove, the live tick must be at or above `tickUpper`. This is checked before token transfer and again after transfer, reducing the chance that a price movement between reads creates an invalid mint.

### 9.2 Width constraints

Ticks must align to pool tick spacing. Range width, measured in tick spacings, must fall between immutable manager limits. These limits prevent accidental zero-width, inverted, microscopic, or excessive values outside the deployed policy.

### 9.3 Tick-deviation protection

The user supplies an expected tick and maximum deviation. The contract compares current pool state with that expectation twice. If the market has moved too far, the transaction reverts rather than minting at stale assumptions.

### 9.4 Exact token behavior

The manager measures its token balance before and after `transferFrom`. The received amount must equal the requested amount. Fee-on-transfer, rebasing during transfer, or otherwise incompatible behavior fails closed.

### 9.5 Minimum-use and liquidity bounds

`amountInMinimumUsed` protects against too little of the net amount entering the position. `minimumLiquidity` protects the resulting liquidity value. The deadline limits how long the signed intent remains usable.

### 9.6 Settlement

The contract approves only the net amount to the canonical position manager. After mint, it resets allowance to zero. The fee transfers to the fee recipient, and unused net input returns to the caller. The manager is designed to retain no routine user balance.

## 10. Auto-close mechanics

### 10.1 Registration prerequisites

The caller must own the NFT. The auto-closer must have token-specific or operator approval. The position must contain liquidity and be outside its range on one side. TWAP duration and rule lifetime must fit immutable bounds. Minimum output must be greater than zero.

### 10.2 Direction selection

If the current tick is below the range, the rule closes above the upper boundary. If the current tick is at or above the range, it closes below the lower boundary. A position currently inside its range cannot register as a fully one-sided exit rule.

### 10.3 Price confirmation

Execution reads spot tick and consults the pool oracle for the requested TWAP period. Both values must satisfy the stored boundary and direction. This makes the rule sensitive to sustained pool price rather than a single instantaneous observation.

### 10.4 Position integrity

The contract confirms that:

- the NFT still belongs to the recorded owner;
- approval remains active;
- token pair and fee still resolve to the stored pool;
- tick bounds match the registered values;
- liquidity remains nonzero;
- the rule has not expired.

Changing or transferring the position invalidates execution until the state is reconciled through cancellation or a new rule.

### 10.5 Net-output protection

The user registers a minimum **net** output. At execution, the contract converts this into a gross minimum that accounts for the snapshotted fee, then supplies token-specific minimums to `decreaseLiquidity`. After collection and fee calculation, the relevant owner output must still meet the stored net requirement.

### 10.6 Atomic distribution

The auto-closer removes all liquidity, collects both tokens to itself, burns the empty NFT, computes distributions, and transfers funds within one transaction. Any revert rolls back the whole sequence.

### 10.7 Owner control

The owner can cancel the rule or revoke approval before execution. They can also manage the standard NFT directly. Direct manual management intentionally bypasses WEALD’s auto-close service and its associated fee.

## 11. Pool creation and liquidity bootstrapping

### 11.1 Inputs

The pool workflow needs:

- token A and token B addresses;
- fee tier;
- human starting price, expressed as token B per token A;
- token decimals;
- aligned lower and upper ticks;
- desired and minimum token amounts;
- minimum resulting liquidity;
- recipient;
- deadline.

### 11.2 Human price conversion

V3 initialization uses `sqrtPriceX96`, a fixed-point square-root price. The SDK handles address sorting and decimal scaling:

```ts
sqrtPriceX96ForHumanPrice(tokenA, tokenB, decimalsA, decimalsB, priceBPerA)
```

This calculation should come from exact decimal input. Floating-point arithmetic is unsuitable for transaction-critical base-unit math.

### 11.3 Atomic sequence

1. Confirm no pool exists at the pair and fee tier.
2. Create and initialize through the WEALD factory path.
3. Confirm the registered pool matches the returned address.
4. Validate tick spacing and initial-price containment.
5. Pull both assets exactly.
6. Deduct bounded creation fees.
7. Approve the position manager for net amounts.
8. Mint the initial position to the recipient.
9. Clear allowances.
10. Transfer fees and return unused tokens.

### 11.4 Economic risks

The creator chooses the initial price. An incorrect price creates an arbitrage opportunity. The pool may have thin liquidity and severe price impact. A full-range position is simple and broadly active while using capital less efficiently than a narrow range. Multiple fee tiers fragment liquidity.

## 12. Fees and worked examples

### 12.1 Current model

The documented V2 model uses:

- creation fee: `1%`, capped on-chain at `1%`;
- optional auto-close fee: `1%`, capped on-chain at `1%`;
- auto-close fee split: `95%` treasury and `5%` executor;
- fee changes: delayed by two days;
- auto-close terms: snapshotted at registration.

Every client should read the live fee controller and active manifest before presenting a quote.

### 12.2 Grove creation example

Input: `10,000` units.
Creation fee at `1%`: `100`.
Maximum net amount offered to V3: `9,900`.

If V3 uses `9,850`, the remaining `50` returns to the caller. The NFT records liquidity corresponding to the amount used.

### 12.3 Auto-close example

Gross collected output: `12,000` units.
Auto-close fee at `1%`: `120`.
Owner output: `11,880`.
Keeper share at `5%` of the fee: `6`.
Treasury share: `114`.

The fee applies independently to each token collected. A properly crossed one-sided position should be dominated by the intended output token, though accrued fees or rounding can produce both assets.

### 12.4 Combined service effect

Applying a 1% creation fee and later a 1% close fee to the remaining value produces an approximate combined service effect of `1.99%`, before swap fees earned, market movement, gas, slippage, price impact, MEV, and token behavior.

## 13. Web application

The public interface is a Next.js application using React and viem-oriented chain integration.

### 13.1 Home

The home page presents live mainnet positioning, the Grove lifecycle, verified pool examples, transaction boundaries, and ownership safeguards. It links directly into discovery, Grove creation, portfolio management, and risk disclosure.

### 13.2 Pools

The Pools workspace supports:

- token-first market grouping;
- search by symbol, name, quote asset, token address, or pool address;
- ranking modes for trending, established, fee activity, new launches, PONS verification, and all markets;
- quote filters;
- observed block and verification state;
- pool metrics and price charts when sourced;
- direct import and verification of a token or pool contract;
- launch provenance for PONS V2/V4 candidates;
- links into Grove creation and position management.

PONS V4 discovery is visible as provenance. V4 write support remains disabled until an audited manager is present in the active mainnet manifest.

### 13.3 Groves

The Grove console drives pool selection, wallet connection, amount and target configuration, protection settings, approval, creation, rule registration, and transaction state. It chain-locks writes and verifies deployed code before signing.

### 13.4 Positions

The Positions workspace focuses on live wallet-owned NFTs and available management actions. It reads ownership and contract state directly. Users can inspect automation state and take supported Uniswap position actions.

### 13.5 Strategies

The strategy library lists deployed capabilities only. It avoids illustrative return claims and routes users to the live workspace and risk documentation.

### 13.6 Activity and analytics

These pages are intentionally honest about data availability. Historical activity stays empty until a complete production event indexer can attach block and transaction provenance. Historical valuation and time-in-range analytics stay empty until reliable indexing and price sources exist.

### 13.7 Developers

The developer area introduces the SDK, manifests, APIs, contract tooling, and integration boundaries.

### 13.8 Risk and settings

Risk explains concentrated-liquidity, market, token, contract, infrastructure, and automation risks. Settings exposes network identity, manifest checksum, active manager and auto-closer addresses, and default transaction protections.

## 14. Pool discovery and market data

### 14.1 Candidate sources

The web discovery layer can combine:

- WEALD-indexed factory events;
- launch-factory events such as PONS;
- GeckoTerminal discovery and chart data;
- DexScreener market analytics;
- direct user-imported addresses.

### 14.2 Canonical verification

Candidate data is advisory until verified. For a V3 candidate, WEALD reads token identities and fee, asks the canonical factory for the corresponding pool, and requires the returned address to match. Symbols, logos, tickers, and third-party URLs never establish write authority.

### 14.3 Data-quality policy

The interface distinguishes live chain reads, indexed history, third-party analytics, and unavailable metrics. When historical evidence is incomplete, the UI says so. This prevents decorative charts or guessed totals from acquiring the appearance of protocol truth.

## 15. Indexer, database, and API

### 15.1 Indexer behavior

The TypeScript indexer watches canonical `PoolCreated` events. It:

- pins Robinhood Chain;
- uses an archive RPC when configured;
- waits for a confirmation distance;
- reads logs in bounded chunks;
- decodes strictly;
- persists raw protocol events and normalized pools;
- stores block-number and block-hash checkpoints;
- detects checkpoint hash mismatch;
- rewinds by a configured reorg depth;
- resumes from the canonical checkpoint.

### 15.2 Database schema

The PostgreSQL foundation contains:

- `indexer_checkpoints`: chain, block number, block hash, update time;
- `pools`: chain, address, token0, token1, fee, tick spacing, creation block;
- `protocol_events`: chain, transaction hash, log index, block metadata, event name, JSON payload.

Writes use explicit database transactions. The schema is compact by design and can be rebuilt from chain history.

### 15.3 API routes

The Fastify API currently exposes:

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/health` | Service, chain, database, and timestamp status |
| `GET` | `/v1/config/chains` | Supported chain metadata |
| `GET` | `/v1/pools` | Cursor-paginated indexed pools |
| `GET` | `/v1/vaults` | Explicit disabled-state response |
| `GET` | `/v1/metrics` | Indexed pool count and completeness |
| `POST` | `/v1/deployment/validate` | Zod validation of deployment manifests |

Pool pagination supports a bounded limit from 1 to 100 and uses creation block as the cursor. When the database is absent, the API returns an explicit incomplete result.

### 15.4 Error behavior

Fastify request IDs flow through logs and error responses. Schema failures return structured errors. Internal failures return a stable error label and request ID for support correlation.

## 16. SDK and integration model

The SDK uses viem types and returns unsigned call descriptions. It does not load private keys or submit transactions.

### 16.1 Manifest functions

- `validateManifest`
- `addressFromManifest`
- `assertManifestReady`

Clients should require the expected chain ID, verified required contracts, complete verification status, and successful smoke-test state.

### 16.2 Pool and Grove builders

- `poolLookup`
- `createPoolCall`
- `bootstrapPoolCall`
- `singleSidedGroveCall`
- `approveTokenCall`

### 16.3 Automation builders

- `approveAutoCloserCall`
- `registerAutoCloseCall`
- `cancelAutoCloseCall`
- `minimumOutputForFullyCrossedPosition`

### 16.4 Position management

- `decreasePositionLiquidityCall`
- `collectPositionCall`
- `burnPositionCall`
- `positionManagerMulticall`

### 16.5 Math and formatting

- `sqrtPriceX96ForHumanPrice`
- `fullRangeTicks`
- `groveTicksForPriceMove`
- `percentageGainAtTickBoundary`
- `feeAmount`
- `amountAfterFee`
- `toBaseUnits`
- `fromBaseUnits`

### 16.6 Example integration

```ts
import {
  validateManifest,
  approveTokenCall,
  singleSidedGroveCall
} from "@weald/sdk";

const manifest = validateManifest(rawManifest, 4663);

const approval = approveTokenCall(tokenIn, groveManager, amountIn);
const creation = singleSidedGroveCall(manifest, {
  tokenA,
  tokenB,
  tokenIn,
  fee: 3_000,
  tickLower,
  tickUpper,
  expectedTick,
  maximumTickDeviation: 20,
  amountIn,
  amountInMinimumUsed,
  minimumLiquidity,
  recipient: account,
  deadline
});

// Present both calls to the wallet for explicit review and signing.
```

Production code should read current contracts, simulate calls, show human-readable values, and recheck chain ID immediately before signing.

## 17. Keeper service

### 17.1 Purpose

The keeper supplies availability for permissionless `execute` calls. Contract logic determines eligibility and settlement.

### 17.2 Startup safety

The mainnet keeper pins:

- chain ID `4663`;
- auto-closer address;
- expected runtime bytecode hash;
- deployment block;
- confirmation depth;
- RPC origin;
- gas caps;
- protected key-file path;
- state-file path.

Startup fails if chain identity or bytecode differs from configuration.

### 17.3 State reconstruction

The service reads confirmed `AutoCloseRegistered`, `AutoCloseCancelled`, and `AutoCloseExecuted` logs. It applies lifecycle events to an active position-ID set. State is written through a temporary file and atomic rename. Each checkpoint includes block identity for safe continuation.

### 17.4 Execution loop

For each active rule, the keeper:

1. checks retry spacing;
2. reads the on-chain rule;
3. drops inactive records;
4. simulates `execute` from the keeper account;
5. estimates gas;
6. enforces configured gas limits;
7. submits the simulated request;
8. waits for required confirmations;
9. updates active state and health metrics.

Expected reverts, such as a boundary that has not crossed, keep the rule active for a later pass.

### 17.5 Key isolation

The keeper uses a dedicated, low-balance gas wallet. The private-key file must have owner-only permissions. It should live outside Git and deployment artifacts. The account has no custody or administrative privilege.

### 17.6 Health

The service exposes a local health endpoint, conventionally `127.0.0.1:4320/health`, with scan state, active rule count, errors, and execution status. Systemd runs it as an unprivileged `weald` user with hardening controls.

## 18. Security model

### 18.1 Core invariants

WEALD’s security work centers on these properties:

1. The Grove NFT is minted directly to the selected owner.
2. Routine creation leaves no user token balance or continuing token allowance in the manager.
3. A single-sided range must align to spacing, remain within width bounds, and sit fully on the correct side of the live tick.
4. Expected-tick deviation is enforced around token movement.
5. Tokens with non-exact transfer behavior are rejected.
6. Auto-close requires current ownership and revocable approval.
7. Active rules bind pool identity, range, direction, fee terms, expiry, TWAP, and minimum output.
8. Spot and TWAP must confirm the boundary.
9. Close settlement is atomic.
10. Derived services cannot alter ownership or settlement.

### 18.2 Threat classes

#### Smart-contract defects

Risks include arithmetic mistakes, state-machine errors, approval misuse, callback or reentrancy problems, incorrect token ordering, and integration mismatch. Defenses include immutable dependencies, reentrancy guards, safe transfer wrappers, exact balance accounting, strict checks, fuzz tests, invariant tests, pinned compiler and dependency versions, bytecode hashes, and staged deployment evidence.

#### Price manipulation

A transient price can affect spot-dependent systems. WEALD auto-close requires spot plus TWAP. This reduces short-lived manipulation risk while retaining exposure to sustained market manipulation, thin liquidity, oracle observation availability, and economic attacks.

#### Malicious or unusual tokens

Fee-on-transfer, rebasing, denylist, pausable, upgradeable, callback-enabled, or misleading tokens can break assumptions. Creation rejects unequal transfer receipt. Users and integrators must still evaluate token contracts and issuer controls.

#### Approval risk

ERC-20 and NFT approvals create authority. WEALD uses exact ERC-20 amounts and clears its temporary position-manager allowance. Auto-close approval is revocable. Wallets should display spender addresses from the verified manifest.

#### Infrastructure failure

RPC outages, reorgs, stale indexers, market-data failures, and keeper downtime affect availability and presentation. Confirmed-log processing, checkpoint hashes, multiple recovery paths, local health checks, and permissionless execution reduce impact.

#### Governance and operator risk

Fee and emergency roles can affect future use of WEALD entry points. Delays, caps, event monitoring, role separation, manifests, and eventual multisig governance constrain this surface. These roles cannot take custody of standard user NFTs through the intended design.

### 18.3 Audit posture

The repository contains internal security notes, threat models, Slither configuration and outputs, fuzz and invariant suites, dependency review, deployment checklists, and verification evidence. The protocol has completed mainnet operator-funded self-tests. Internal review and live tests cannot eliminate undiscovered defects.

Test counts in historical documents represent their review date. New contracts and test additions increase the suite over time. The source tree and current CI result are authoritative for a given commit.

### 18.4 User security checklist

Before signing:

- confirm Robinhood Chain and chain ID `4663`;
- verify contract addresses against the active checksummed manifest;
- inspect token contracts and decimals;
- understand which address becomes `token0`;
- verify pool fee tier and current tick;
- review amount, deadline, tick deviation, minimum used, and minimum liquidity;
- inspect fee rates from the live controller;
- understand auto-close expiry, TWAP, minimum net output, and NFT approval;
- keep native gas for later management;
- preserve a direct position-manager recovery path.

## 19. Roles, governance, and emergency controls

WEALD separates responsibilities across access management, fee control, guardian operations, deployment provenance, and permissionless execution.

Administrative changes should follow delayed, observable paths. Fee changes have an explicit delay and cap. Emergency pause bits apply to named WEALD operations. Keeper execution has no role. Upstream Uniswap ownership remains with the NFT owner.

For a mature public release, operational ownership should use a reviewed multisig, documented signers, hardware-backed keys, transaction simulation, timelock monitoring, and rehearsed incident procedures. Role changes and pause actions should trigger alerts.

## 20. Token compatibility

### 20.1 Standard tokens

Ordinary ERC-20 tokens with stable balances, conventional `transferFrom`, reliable decimals, and no transfer deductions fit the intended manager path.

### 20.2 Restricted tokens

Tokens may impose allowlists, sanctions controls, market hours, transfer pauses, issuer freezes, redemption constraints, or jurisdiction rules. A successful on-chain transfer does not remove those risks.

### 20.3 Unsupported transfer behavior

The Grove manager and bootstrapper reject a token when the balance received differs from the exact requested amount. This covers many transfer-tax tokens. Rebasing and callback behavior can create additional incompatibilities.

### 20.4 Upgradeable tokens

An upgradeable token can change after a position is created. Users should examine proxy admin, implementation, upgrade delay, and issuer authority.

### 20.5 Tokenized stocks and real-world assets

Tokenized securities or stock-like assets may carry issuer, market-hours, legal, oracle, bridge, redemption, corporate-action, and transfer restrictions beyond AMM risk. WEALD does not turn a token into a regulated claim or guarantee redemption parity.

## 21. Deployment provenance and live addresses

### 21.1 Mainnet upstream

| Component | Address |
|---|---|
| Official V3 Factory | `0x1f7d7550B1b028f7571E69A784071F0205FD2EfA` |
| Official Nonfungible Position Manager | `0x73991a25C818Bf1f1128dEAaB1492D45638DE0D3` |

### 21.2 Mainnet WEALD

| Component | Address |
|---|---|
| WealdAccessManager | `0x0651737607ECc2f69bB7d6b573F141C3b39e7230` |
| WealdEmergencyGuardian | `0xb2c8f94789F346e8f5e255817d91cF23Dc770632` |
| WealdFactory | `0xAa2248F01BC9F2072C3B501818eE295e8f537B16` |
| SingleSidedGroveManager V1 | `0x7E534C728F642B7Bae32f533FA6703465c63e76A` |
| GroveAutoCloser V1 | `0xAd4Fdb96FC6afF932D9c7a3C1F7aB9976a05E768` |
| GroveFeeController V2 | `0x9d25d4bf8495139402BD089336F99549F2f56F0a` |
| SingleSidedGroveManager V2 | `0x0F243804fBc44b5A3b9615cE74Bfa17d473e32FC` |
| GroveAutoCloser V2 | `0x500C04990899F54670d15DFDc87B1cec46430dcB` |
| TwoSidedPoolBootstrapper | `0xe0F069D8D80E968133760619c45283F1e0719791` |
| SingleSidedPoolBootstrapper | `0x2B4230AefC1Bd3E794d7ca639CBCD2c31971fa82` |

Addresses are reference material. Clients must validate the active append-only mainnet manifest and its SHA-256 checksum before use.

### 21.3 Manifest lineage

The mainnet deployment record is append-only:

- `manifest.json`: initial Phase 1 deployment;
- `manifest-v2.json`: V2 fee and Grove modules;
- `manifest-v3.json`: two-sided pool bootstrapper release;
- `manifest-v4.json`: immutable single-sided pool bootstrapper release record.
- `manifest-v5.json`: current active application manifest with completed executed-and-burned mainnet smoke evidence.

The reviewed operations record identifies source commit `fd2b…` for the deployed release lineage and records the current manifest checksum in the repository. Read the full manifest for exact hashes, transactions, blocks, roles, verification, and smoke-test evidence.

## 22. Repository and technology stack

### 22.1 Monorepo layout

```text
weald/
├── apps/
│   ├── admin/       administrative interface foundation
│   ├── api/         Fastify derived-data API
│   ├── indexer/     confirmed-log pool indexer
│   ├── keeper/      permissionless auto-close executor
│   └── web/         public Next.js application
├── packages/
│   ├── abis/        typed contract ABIs
│   ├── config/      chain and manifest schemas
│   ├── contracts/   Solidity contracts, scripts, and tests
│   ├── database/    PostgreSQL connection and schema
│   ├── sdk/         unsigned call builders and math
│   └── ui/          shared UI foundation
├── deployments/     append-only manifests and service configs
├── docs/            design, operations, integration, and decisions
├── monitoring/      Prometheus, Grafana, alerts, and runbooks
├── scripts/         audit, deployment, checksum, and verification tools
└── security/        threat models, review evidence, and disclosures
```

### 22.2 Stack

| Layer | Technology |
|---|---|
| Monorepo | pnpm workspaces, Turborepo |
| Runtime | Node.js 22 |
| Language | TypeScript 5.9 |
| Web | Next.js 15.5, React 19.1 |
| API | Fastify 5.11 |
| EVM client | viem 2.55 |
| Validation | Zod 4 |
| Database | PostgreSQL via `pg` |
| Logging | Pino |
| Contracts | Solidity 0.8.26 |
| Contract toolchain | Foundry, forge, cast, Anvil |
| Security libraries | OpenZeppelin 5.4 |
| AMM dependencies | Uniswap V3 core/periphery; staged V4 packages |
| Monitoring | Prometheus and Grafana examples |
| Process control | systemd service units |
| Edge | Nginx deployment configuration |

### 22.3 Package responsibilities

`@weald/config` prevents unsupported chain IDs and invalid manifests from reaching clients. `@weald/abis` centralizes interfaces. `@weald/sdk` owns deterministic transaction construction and math. `@weald/database` keeps persistence small and transactional. Apps compose these packages without acquiring signing authority.

## 23. Local development

### 23.1 Prerequisites

- Node.js 22;
- pnpm 11;
- Foundry toolchain;
- PostgreSQL for indexer/API persistence;
- an RPC appropriate to the selected environment.

### 23.2 Install

```bash
corepack enable
pnpm install --frozen-lockfile
```

### 23.3 Common checks

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

Package-level commands can be run through pnpm filters. Contract tests run from `packages/contracts` with Foundry.

### 23.4 Local chain

Anvil supports deterministic local testing. Deployment scripts should use disposable local keys. Mainnet or testnet keys belong outside the repository in protected runtime credentials.

### 23.5 Environment handling

Use `.env.example` as a names-only reference. Keep `.env`, private keys, databases, state files, RPC credentials, and deployment secrets outside Git. Production services should receive secrets through protected files or systemd credentials.

## 24. Testing and verification

### 24.1 Contract tests

The Foundry suite covers access control, emergency behavior, factories, fee controllers, Grove managers, auto-closers, lens behavior, descriptors, native wrapping, pool bootstrapping, deployment simulation, and recovery operations.

High-value cases include:

- tick alignment and range orientation;
- price movement between validation points;
- transfer-tax rejection;
- exact approval cleanup;
- fee caps and delayed changes;
- fee snapshots;
- expiry and TWAP bounds;
- ownership or position mutation;
- output-minimum conversion;
- permissionless execution;
- atomic settlement;
- duplicate-pool rejection;
- refund accounting;
- pause scope.

### 24.2 TypeScript tests

API tests cover route shape, validation, pagination, and disabled states. Indexer tests cover decoding, ranges, checkpoints, and reorg handling. Keeper tests cover configuration, lifecycle events, scanning, and execution decisions. SDK tests cover manifest checks, call encoding, fixed-point price math, ticks, fees, and unit conversion.

### 24.3 Static analysis

Security review includes Slither configuration, dependency scanning, compiler warnings, source review, and manual invariant mapping. Tool output must be interpreted within the pinned dependency graph.

### 24.4 Deployment verification

Each release should record:

- Git commit;
- compiler version and optimizer settings;
- constructor arguments;
- deployment transaction and block;
- runtime bytecode hash;
- explorer verification;
- roles and delays;
- upstream source and artifact hashes;
- smoke-test results;
- signed manifest checksum.

## 25. Production operations

### 25.1 Release sequence

The documented flow is:

1. freeze and review source commit;
2. run lint, types, unit, fuzz, invariant, and build checks;
3. validate dependency and upstream hashes;
4. run deployment preflight;
5. simulate against a fork;
6. review predicted addresses, calldata, balances, roles, and gas;
7. require an explicit operator acknowledgement;
8. broadcast staged contracts;
9. wait for confirmations;
10. verify source and runtime bytecode;
11. run read-only and funded smoke tests;
12. write a new append-only manifest;
13. update application configuration to the exact manifest;
14. enable services only after health checks pass.

### 25.2 Mainnet lessons from self-testing

The operator-funded self-test exercised swaps, Grove creation, fee claims, partial and full position management, and auto-close registration/cancellation across several live markets.

A key operational lesson is to read the actual token ID from the mint receipt. The canonical position manager uses a global NFT sequence. Precomputing a token ID from local assumptions can target the wrong position.

### 25.3 Service deployment

Production runs under the existing WEALD deployment target and server policy. Application releases should come from a tested, pushed commit. Service users remain unprivileged. Runtime state, logs, and credentials stay outside the repository and release artifact.

## 26. Monitoring and incident response

### 26.1 Contract monitoring

Alert on:

- emergency pause changes;
- access-role grants and revocations;
- proposed and activated fee changes;
- fee-recipient changes;
- registry or manifest mismatch;
- unexpected contract ETH or token balances;
- runtime bytecode mismatch;
- abnormal auto-close failures.

### 26.2 Keeper monitoring

Track:

- last scanned and confirmed blocks;
- active rule count;
- RPC latency and failure rate;
- simulation failure categories;
- executor balance;
- transaction confirmations;
- retry age;
- state-file persistence;
- health endpoint availability.

### 26.3 Indexer monitoring

Track head lag, checkpoint age, block-hash mismatch, rewind count, log-range failures, database errors, and throughput. Archive RPC behavior should be tested at the oldest required deployment block.

### 26.4 Web and API monitoring

Track local health, request latency, error rate, manifest checksum, canonical factory reads, upstream market-data degradation, and chain mismatch attempts.

### 26.5 Incident priorities

1. Preserve user ownership and prevent unsafe new entry through scoped pause controls.
2. Establish canonical chain state and affected contract versions.
3. Keep direct recovery instructions available.
4. Reconcile submitted transactions before retrying.
5. Publish factual scope, blocks, transactions, and remediation status.

## 27. Recovery and protocol independence

### 27.1 Position recovery

Because Groves are standard NFTs, the owner can interact with the official position manager directly:

- `collect` accrued tokens;
- `decreaseLiquidity` partially or fully;
- `safeTransferFrom` the NFT;
- revoke an auto-closer approval;
- `burn` after liquidity and owed tokens reach zero.

### 27.2 Automation recovery

The owner can call `cancel` on the correct auto-closer version or revoke approval at the NFT contract. An expired or ineligible rule does not transfer ownership.

### 27.3 Service independence

The public keeper can be replaced by any executor. The API and indexer can be rebuilt. The website can be replaced by the SDK or direct ABI calls. The active manifest and verified explorer records tie those tools back to deployed bytecode.

## 28. Current limits and roadmap boundaries

### 28.1 Live boundary

The live product centers on V3 discovery, user-owned positions, Grove creation, management, auto-close, and new-pool bootstrapping.

### 28.2 Public-production gates

The documented gates include:

- independent audit;
- mature multisig and timelock operations;
- sustained monitoring history;
- public bug bounty;
- extended keeper and indexer operating evidence;
- legal and licensing review;
- deeper review for tokenized real-world assets.

### 28.3 Vaults

Automated-liquidity vaults belong to a later phase. The API returns an explicit disabled state. A future vault system would require deposit accounting, share math, strategy constraints, oracle policy, rebalancing safeguards, withdrawal guarantees, new audits, and a distinct trust analysis.

### 28.4 Incentives

WEALD has no live protocol token or Phase 1 liquidity mining. Incentive design would add emissions, sybil, governance, liquidity-migration, and regulatory concerns.

### 28.5 V4 and launchpad integrations

The repository contains PONS V4 discovery and contract work. The web app labels launch provenance and keeps write actions disabled until the relevant audited contracts enter the active manifest. This pattern lets discovery arrive before transaction authority.

### 28.6 Analytics

Complete event history, portfolio valuation, fee history, time-in-range, and performance attribution require a production indexer plus reliable price sources. WEALD keeps unavailable metrics visibly unavailable.

## 29. Troubleshooting

### “Pool not found”

Confirm both token addresses and fee tier. Ask the canonical factory for the pool. A pair can exist at another fee tier. A launch page can reference a market that has not graduated or created its V3 pool.

### “Pool already exists”

The bootstrapper only creates a new pool. Use the existing-pool liquidity path and verify current price before minting.

### “Range not single sided”

The selected range is inside or on the wrong side of the live tick for the input token. Refresh pool state and recalculate using canonical token order.

### “Tick deviation exceeded”

Price moved beyond the user’s tolerance after quote construction. Refresh and review a new range instead of broadening protection automatically.

### “Unsupported token behavior”

The contract received a different amount from the requested transfer. Investigate transfer tax, rebasing, restrictions, proxy changes, or malicious token behavior.

### “Insufficient liquidity” or minimum amount failure

The mint result fell below the signed bound. Refresh pool state, inspect range and amounts, and choose new minimums with explicit user consent.

### Auto-close registration fails

Check NFT ownership, approval, liquidity, range position, TWAP bounds, expiry bounds, and correct auto-closer version.

### Auto-close execution keeps reverting

The rule may be active while spot or TWAP remains short of the boundary. It may also have expired, lost approval, changed ownership, changed liquidity, or fail minimum output. Simulate and classify the exact revert.

### Position does not appear

Read the owner’s NFTs from the canonical position manager and inspect mint receipt logs. Do not infer the global token ID. Confirm the wallet and chain.

### API returns empty data

The database may be disabled, the indexer may be behind, or the route may intentionally expose an incomplete state. Use direct chain reads and inspect `/health` plus completeness fields.

### Keeper is behind

Check local health, RPC access to the deployment block, confirmed head, state-file permissions, runtime bytecode pin, executor gas balance, and systemd logs.

## 30. Glossary

**AMM:** On-chain market whose pricing and liquidity follow a contract algorithm.
**Approval:** Permission allowing a contract to transfer an ERC-20 amount or manage an NFT.
**Basis point:** One hundredth of one percent. `100 bps = 1%`.
**Canonical factory:** The pinned official factory used to verify pool identity.
**Concentrated liquidity:** Liquidity active within a chosen price range.
**Executor:** Address that calls an eligible permissionless auto-close.
**Fee tier:** Swap fee encoded into a V3 pool’s identity.
**Grove:** WEALD’s guarded workflow around a user-owned V3 position.
**Keeper:** Off-chain service that monitors and executes eligible rules.
**Liquidity:** The V3 position quantity derived from tokens and range math.
**Manifest:** Checksummed deployment record containing addresses, bytecode, roles, and evidence.
**Minimum net output:** Owner’s required proceeds after the auto-close fee.
**NFT:** Non-fungible token representing ownership of a V3 position.
**Out of range:** Pool price lies outside the position’s active interval.
**Permissionless:** Callable by any address that satisfies contract conditions.
**Range order:** Informal use of concentrated liquidity to convert assets as price traverses a range.
**Reorg:** Chain history replacement near the head, handled through confirmation depth and checkpoint hashes.
**Slippage:** Difference between expected and realized execution amounts.
**Spot tick:** Current V3 pool tick.
**`sqrtPriceX96`:** V3’s fixed-point square-root price representation.
**Tick:** Logarithmic price index used by V3.
**Tick spacing:** Required interval between usable ticks for a fee tier.
**TWAP:** Time-weighted average price calculated from pool observations.
**V3:** Uniswap concentrated-liquidity design using position NFTs.
**V4:** Newer singleton-and-hooks architecture, represented in WEALD as a gated integration track.
**WETH:** Wrapped form of the chain’s native ETH used as an ERC-20.

## 31. Source map

This knowledge base was assembled from the live repository and its project memory. The highest-value references are:

| Topic | Source |
|---|---|
| Product overview and phase status | `README.md` |
| Architecture boundaries | `docs/ARCHITECTURE.md` |
| Product decisions | `docs/PROTOCOL_DECISIONS.md` |
| Fee behavior | `docs/FEE_MODEL.md` |
| Pool creation | `docs/POOL_CREATION.md` |
| Direct NFT recovery | `docs/LP_RECOVERY.md` |
| Keeper operations | `docs/KEEPER_OPERATIONS.md` |
| Mainnet evidence | `docs/MAINNET_OPERATIONS.md` |
| Monitoring | `docs/MONITORING.md`, `monitoring/` |
| API | `docs/API.md`, `apps/api/` |
| SDK | `docs/SDK.md`, `packages/sdk/` |
| Security model | `security/`, `docs/SECURITY.md` |
| Deployments | `deployments/mainnet/`, `deployments/testnet/` |
| Contracts | `packages/contracts/src/` |
| Contract tests | `packages/contracts/test/` |
| Web features | `apps/web/src/` |
| Indexer | `apps/indexer/src/` |
| Keeper | `apps/keeper/src/` |
| Database | `packages/database/src/` |

### Final integration principle

Treat the active checksummed manifest, verified deployed bytecode, canonical factory, and current chain state as authoritative. Treat interfaces, indexers, APIs, charts, and this document as tools for understanding that state. Every transaction should remain explicit, simulated, bounded, and signed by the wallet that owns the action.

---

*WEALD is experimental third-party software. Concentrated liquidity and automated execution can lose value. Users remain responsible for token, market, contract, chain, and legal risk.*