# Fork Ancestry

> Trigger Pattern Always (run during recon TASK 0, not breadth) - Inject Into Recon agent only (meta_buffer.md enrichment)

- Skill: `plamentsv/fork-ancestry-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add plamentsv/fork-ancestry-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/plamentsv/fork-ancestry-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: plamentsv (https://skillmd.com/u/plamentsv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/plamentsv/fork-ancestry-2

---


# FORK_ANCESTRY Skill (Sui)

> **Trigger Pattern**: Always (run during recon TASK 0, not breadth)
> **Inject Into**: Recon agent only (meta_buffer.md enrichment)
> **Finding prefix**: `[FA-N]`
> **Purpose**: Detect known parent Sui packages and inherit their historical vulnerability patterns.

---

## 1. Detect Fork Indicators

Grep the codebase for known parent Sui package signatures:

| Parent Project | Detection Patterns | Common Forks |
|---------------|-------------------|--------------|
| Cetus | `cetus\|clmm\|tick\|concentrated_liquidity\|cetus_clmm\|tick_math\|sqrt_price_math\|CetusPool` | Concentrated liquidity forks |
| Suilend | `suilend\|lending_market\|reserve\|obligation\|refresh_reserve\|LendingMarket\|ObligationKey` | Lending protocol forks |
| NAVI | `navi\|navi_protocol\|lending\|pool_manager\|incentive\|StoragePool\|navi_lending` | Lending protocol forks |
| Scallop | `scallop\|s_coin\|market\|obligation\|borrow_dynamics\|ScallopMarket\|sCoin` | Lending protocol forks |
| Turbos | `turbos\|pool_factory\|position_manager\|turbos_clmm\|TurbosPool\|TurbosPosition` | Concentrated liquidity forks |
| Curve StableSwap | `stable_swap\|stableswap\|get_d\|get_y\|ramp_a\|stop_ramp_a\|A_PRECISION\|RATE_MULTIPLIER\|calc_withdraw_one_coin\|remove_liquidity_imbalance\|get_virtual_price\|admin_fee` | StableSwap AMM forks — **set STABLESWAP_FORK flag if MEDIUM+ confidence** |
| DeepBook | `deepbook\|clob\|order_book\|custodian\|deep_book\|DeepBookPool\|BalanceManager` | Order book DEX forks |
| Aftermath | `aftermath\|af_lp\|pool_registry\|amm_v2\|AftermathPool\|StakedSui` | AMM / liquid staking forks |
| Bucket | `bucket\|bucket_protocol\|tank\|well\|fountain\|BucketProtocol\|BUCK` | Stablecoin / CDP forks |
| Kriya | `kriya\|kriya_dex\|spot_dex\|clmm\|KriyaPool\|KriyaPosition` | DEX forks |
| FlowX | `flowx\|flowx_clmm\|router\|pair_v2\|FlowXPool\|FlowXRouter` | DEX forks |
| Sui System Staking | `staking_pool\|validator\|sui_system\|delegation\|StakedSui\|StakingPool\|ValidatorCap` | Liquid staking / validator forks |

**Also check**:
- `Move.toml` dependencies for parent package addresses or names (e.g., `cetus_clmm = "0x..."`, `deepbook = { addr = "0x..." }`)
- Import paths in Move source: `use cetus_clmm::`, `use deepbook::`, `use suilend::`, etc.
- Struct names and function signatures matching known parent interfaces
- Published package addresses in dependency declarations (known mainnet addresses of parent protocols)

**Git-based detection** (complements code-pattern matching — catches forks that renamed all identifiers).
Skip if `REPO_SHAPE: squashed_import` in `build_status.md` — single-commit repos have no meaningful git metadata.
- Parse `.gitmodules` for submodule URLs pointing to known parent repos
- Check `git remote -v` for origin URLs matching known Sui parent organizations (MystenLabs, cetus-technology, scallop-io, navi-protocol, suilend, deepbook, turbos-finance)
- If a git-URL match is found but NO code-pattern match exists, flag as `GIT_ONLY_FORK`

**Output**: List of detected parents with confidence level:
- **HIGH**: 3+ unique patterns matched, OR parent package in Move.toml dependencies
- **MEDIUM**: 2 patterns matched
- **LOW**: 1 pattern matched (may be coincidental naming)
- **GIT_ONLY**: git URL match but no code patterns — fork likely renamed identifiers

---

## 2. Query Known Parent Issues

For each detected parent (confidence MEDIUM or HIGH):

### 2a. Solodit Search (two queries, run in parallel)
```
// Query 1: Known high-quality issues
search_solodit_live(
  keywords="{parent_name} sui move",
  impact=["HIGH", "CRITICAL"],
  language="Move",
  quality_score=3,
  sort_by="Quality",
  max_results=15
)
// Query 2: Fork-specific divergence issues
search_solodit_live(
  keywords="{parent_name} fork modified sui object",
  impact=["HIGH", "MEDIUM"],
  language="Move",
  sort_by="Rarity",
  max_results=10
)
```

### 2b. Tavily Search
```
tavily_search(query="{parent_name} sui move vulnerability exploit audit finding 2024 2025 2026")
```

### 2c. Known Issue Catalog

Compile results into:

| Parent | Known Issue | Severity | Root Cause | Solodit Ref | Applicable to Fork? |
|--------|-----------|----------|------------|-------------|---------------------|
| {parent} | {issue title} | {severity} | {brief root cause} | {link/ID} | YES / NO / CHECK |

**Applicability criteria**:
- **YES**: Fork retains the vulnerable code path unchanged
- **NO**: Fork modified the vulnerable code path (document what changed)
- **CHECK**: Cannot determine without deeper analysis (flag for breadth agent)

### 2d. Hardcoded Known-Issue Floor (Web Search Fallback)

If Solodit AND Tavily BOTH fail, use this minimum catalog -- check EACH applicable parent.

This floor is keyed on the parent's **TYPE** (generic mechanism), NOT on any
specific protocol name — brand-keyed rows are prohibited (a floor row naming a
specific protocol is the confirmed benchmark-contamination vector; see the HARD
no-overfit rule). Classify the detected parent (from Section 1) into a type
below and check the generic known-issue class; use at most one illustrative
brand only in prose, never as the row key.

| Parent Type | Critical Known Issue | Root Cause | Search Keywords |
|--------|---------------------|------------|-----------------|
| CLMM DEX | Tick boundary crossing precision loss + liquidity accounting desync | sqrt_price calculation at tick boundaries, Position NFT state vs pool liquidity mismatch | `clmm tick precision sqrt_price` |
| Lending protocol (obligation-based) | Obligation refresh staleness + liquidation racing on shared objects | Reserve refresh not enforced before obligation health check, concurrent tx ordering | `lending obligation refresh stale liquidation shared object` |
| Lending protocol (pool-based) | Pool balance desync via flash loan deposit/withdraw + incentive calculation overflow | Balance tracking diverges from actual Coin balance, large TVL causes incentive arithmetic overflow | `lending balance flash loan pool desync` |
| Lending protocol (receipt-token) | Receipt token exchange rate manipulation via first depositor + borrow dynamics staleness | Empty market rounding in receipt token minting, stale interest rate applied across epochs | `lending receipt token exchange rate first deposit borrow dynamics` |
| Orderbook DEX | Order matching priority manipulation + balance manager accounting edge cases | Self-trading for priority manipulation, dust amounts in partial fills | `orderbook order priority self-trade balance dust` |
| CDP/stablecoin protocol | Reward distribution fairness + overflow at extreme collateral ratios | Discrete epoch distribution timing, arithmetic overflow in collateral ratio calculation | `cdp reward epoch collateral overflow` |
| Liquid staking / validator protocol | Validator list manipulation via stake deposit ordering + reward fee timing | Stake account priority ordering in validator selection, reward distribution during epoch boundary | `sui staking validator reward epoch boundary` |
| AMM / LP share pool | LP share price manipulation via donation to pool + liquid-staking-token exchange rate lag | Direct Coin transfer to pool object inflates share price, staking rewards not reflected immediately in the receipt token's exchange rate | `amm pool share price donation staking token exchange rate` |

---

## 3. Divergence Analysis

For each detected parent:

### 3a. Identify What Changed

Compare fork vs parent in security-critical paths:

| Component | Parent Behavior | Fork Behavior | Security Impact |
|-----------|----------------|---------------|-----------------|
| {component} | {original} | {modified or SAME} | {new risk or NONE} |

**Sui-specific divergence focus areas** (ordered by criticality):

#### Object Ownership Model Changes (HIGHEST PRIORITY)
- Did the fork change any object from OWNED to SHARED or vice versa? Ownership model changes fundamentally alter the access control surface.
- Did the fork add or remove `store` ability from objects? Adding `store` = anyone can transfer; removing `store` = module-controlled transfer only.
- Did the fork change shared object access control patterns (different capability checks, different admin verification)?
- **Critical**: Shared object without proper access control = anyone can mutate protocol state.

#### Capability and Admin Pattern Changes
- Did the fork change which capabilities gate admin operations (different Cap objects, different verification logic)?
- Did the fork add `store` to capability objects that the parent kept module-restricted? This allows capability transfer, potentially weakening admin control.
- Did the fork introduce new admin functions without corresponding capability checks?
- **Critical**: Capability objects with `store` can be transferred to arbitrary addresses, including contracts that auto-execute.

#### Balance and Coin Handling Changes
- Did the fork modify how `Balance<T>` or `Coin<T>` objects are split, joined, or transferred?
- Are there new code paths where Balance could be created (via `balance::zero()` then never destroyed) or destroyed (via unmatched `balance::destroy_zero()`)?
- Did the fork add support for additional coin types without updating all code paths?
- **Critical**: Balance accounting mismatches between protocol state and actual Coin holdings.

#### Dynamic Field Schema Changes
- Did the fork change dynamic field key types or naming conventions?
- Are there new dynamic field additions without corresponding removal logic?
- Did the fork change which objects have dynamic fields attached?

#### Other Divergence Areas
- Modified mathematical formulas (fee calculations, exchange rates, reward distribution)
- **Parameter semantic verification**: When the parent has a mathematical specification, verify that each core parameter carries the same mathematical meaning in the fork — not just the same name and numeric range. Forks may store a raw value where the parent stores a derived form (e.g., raw coefficient vs. coefficient scaled by a function of pool dimensions). Compare the fork's formula usage against the parent's specification to confirm the encoding convention matches.
- Changed access control (added/removed capabilities, modified authority checks)
- Removed safety checks (assertions removed, constraints removed)
- Changed struct layouts (fields reordered, types changed, new fields added)
- Added/removed public functions (new attack surface or missing safety functions)
- Changed event emissions (may affect off-chain monitoring and indexers)

### 3b. New Attack Surface from Divergence

For each modification:
- Does the change introduce a NEW vulnerability not in the parent?
- Does the change REMOVE a parent fix/mitigation?
- Does the change create an INCONSISTENCY with parent's invariants?
- **Does the change break assumptions that other unchanged code relies on?** (e.g., parent assumes PoolConfig is always shared; fork sometimes wraps it inside another object)

---

## 4. Output to meta_buffer.md

Append to `{SCRATCHPAD}/meta_buffer.md`:

```markdown
## Fork Ancestry Analysis

### Detected Parents
| Parent | Confidence | Patterns Found | Move.toml Dependency? |
|--------|-----------|---------------|----------------------|

### Inherited Vulnerabilities to Verify
| # | Parent Issue | Severity | Location in Fork | Status |
|---|-------------|----------|------------------|--------|
| 1 | {issue} | {severity} | {fork location: module::function} | CHECK / VERIFIED_SAFE / VULNERABLE |

### Fork Divergences (Security-Critical)
| # | Component | Change Type | Change Description | New Risk? |
|---|-----------|------------|-------------------|-----------|
| 1 | {component} | OWNERSHIP_MODEL / CAPABILITY / BALANCE / DYNAMIC_FIELD / OTHER | {what changed} | YES/NO/CHECK |

### Questions for Breadth Agents
1. {derived from inherited vulnerabilities}
2. {derived from divergence analysis}
3. {derived from ownership model changes}
```

---

## Step Execution Checklist (MANDATORY)

| Section | Required | Completed? | Notes |
|---------|----------|------------|-------|
| 1. Detect Fork Indicators | YES | Y/N/? | Check Move.toml deps + source patterns |
| 2. Query Known Parent Issues | IF parent detected | Y/N(no parent)/? | |
| 2d. Hardcoded Known-Issue Floor | IF Solodit+Tavily both fail | Y/N(not needed)/? | |
| 3. Divergence Analysis | IF parent detected | Y/N(no parent)/? | |
| 3a. Object Ownership Model Changes | IF parent detected | Y/N(no parent)/? | Highest priority |
| 3a. Capability and Admin Pattern Changes | IF parent detected | Y/N(no parent)/? | |
| 3a. Balance and Coin Handling Changes | IF parent detected | Y/N(no parent)/? | |
| 3a. Dynamic Field Schema Changes | IF parent detected | Y/N(no parent)/? | |
| 4. Output to meta_buffer.md | YES | Y/N/? | |

### Cross-Reference Markers

**After Step 1**: If Move.toml shows specific parent package address dependencies, verify the addresses match known mainnet deployments (not test/devnet).

**After Step 3a (Ownership Model)**: Feed changed ownership models to OBJECT_OWNERSHIP skill for targeted re-analysis of affected objects.

**After Step 3a (Capability)**: Feed new/changed capabilities to SEMI_TRUSTED_ROLES skill for admin privilege analysis.

**After Step 3a (Balance)**: Feed changed balance handling to TOKEN_FLOW_TRACING skill for flow analysis.