Fork Ancestry

FORK_ANCESTRY Skill (Soroban)

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 Soroban contracts and Stellar DeFi ecosystem projects, and inherit their historical vulnerability patterns.

1. Detect Fork Indicators

Grep the codebase for known parent Soroban/Stellar project signatures:

Also check:

• Cargo.toml dependencies for parent crate names (e.g., blend-contract-sdk, phoenix-dex, soroswap-lib)
• Import paths in Rust source: use blend_contract_sdk::, use phoenix::, etc.
• Contract interface declarations matching known parent project method signatures
• soroban-sdk version in Cargo.toml (soroban-sdk = "X.Y.Z") — known vulnerabilities per SDK version

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 Stellar/Soroban organizations (stellar, soroswap, blend-capital, phoenix-protocol, esteblock)
• 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 crate in Cargo.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} soroban stellar",
  impact=["HIGH", "CRITICAL"],
  language="Rust",
  quality_score=3,
  sort_by="Quality",
  max_results=15
)
// Query 2: Fork-specific divergence issues
search_solodit_live(
  keywords="{parent_name} fork modified soroban",
  impact=["HIGH", "MEDIUM"],
  language="Rust",
  sort_by="Rarity",
  max_results=10
)

2b. Tavily Search

tavily_search(query="{parent_name} soroban stellar contract vulnerability exploit audit finding 2024 2025 2026")

2c. Known Issue Catalog

Compile results into:

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 dependency'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 into a type below and check the generic hazard class.

3. Divergence Analysis

For each detected parent:

3a. Identify What Changed

Compare fork vs parent in security-critical paths:

Soroban-specific divergence focus areas (ordered by criticality):

Authorization Changes (HIGHEST PRIORITY)

Soroban uses a capability-based auth model (env.require_auth(&address)). Unlike EVM's msg.sender, auth must be explicitly required for each address that should authorize a call.

• Did the fork add or remove require_auth calls?
• Did the fork change WHICH address is authorized (e.g., changed from admin to user or removed auth entirely)?
• Did the fork use require_auth_for_args (more restrictive — limits auth to specific arguments) vs plain require_auth (allows authorization for any arguments)?
• Critical: Removing require_auth from a state-modifying function means ANY caller can execute it.
• Did the fork add mock_all_auths() in non-test code? (This disables auth entirely — a catastrophic mistake if left in production.)

Storage Key Changes

• Did the fork change storage key definitions (different Symbol, different enum variant, different data key type)?
• Changed keys can cause: ghost state (old data at old key remains readable), data unavailability (new key finds nothing), privilege bypass (auth data at different key not checked).
• Check: are storage key definitions consistent between ALL functions that read and write the same logical value?

External Contract Address Changes

• Did the fork change which external contracts are called?
• Are new external contract addresses validated and access-controlled?
• Did the fork add calls to contracts not in the parent? (New external dependency = new attack surface)
• Critical: invoke_contract with an unvalidated address allows the admin (or an attacker who can set the address) to redirect calls to a malicious contract.

Token Interface Changes

• Did the fork switch between SAC (Stellar Asset Contract) and a custom token implementation?
• SAC and custom tokens have different trust models: SAC is governed by Stellar core; custom tokens can be upgraded or have non-standard behavior.
• Did the fork add support for tokens with non-standard transfer behavior (e.g., fee-on-transfer tokens)?
• Check: does the fork correctly handle the case where token::Client::transfer succeeds but the received amount is less than requested (fee-on-transfer)?

Mathematical Formula Changes

• Modified interest rate formulas, fee calculations, exchange rates, reward distributions
• Even small arithmetic changes (different rounding direction, different precision) can cause systematic economic attacks over time
• Check: are constants (basis points, precision factors, time units) consistent between the fork and parent?
• 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.

Other Divergence Areas

• Changed access control (added/removed admin roles, modified role hierarchy)
• Removed safety checks (validation removed, bounds check removed)
• Changed storage type (temporary → persistent or vice versa) — TTL semantics differ
• Added/removed functions (new attack surface or missing safety functions)

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 admin is always set; fork adds ability to clear admin)

4. Output to meta_buffer.md

Append to {SCRATCHPAD}/meta_buffer.md:

## Fork Ancestry Analysis

### Detected Parents
| Parent | Confidence | Patterns Found | soroban-sdk Version |
|--------|-----------|---------------|---------------------|

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

### Fork Divergences (Security-Critical)
| # | Component | Change Type | Change Description | New Risk? |
|---|-----------|------------|-------------------|-----------|
| 1 | {component} | AUTH / STORAGE_KEY / EXTERNAL_ADDRESS / TOKEN_INTERFACE / MATH / OTHER | {what changed} | YES/NO/CHECK |

### soroban-sdk Version Vulnerabilities
| Version | Known Issue | Applicable? |
|---------|-----------|-------------|
| {version from Cargo.toml} | {known issue for this version} | YES/NO |

### Questions for Breadth Agents
1. {derived from inherited vulnerabilities}
2. {derived from divergence analysis}
3. {derived from external address changes}

Step Execution Checklist (MANDATORY)

Cross-Reference Markers

After Step 1: If soroban-sdk version detected -> check against known SDK version vulnerabilities immediately.

After Step 3a (Authorization): Feed changed/removed require_auth calls to breadth agents for targeted re-analysis of all state-modifying functions.

After Step 3a (Storage Key): Feed changed key definitions to depth-state-trace for ghost state and privilege bypass analysis.

After Step 3a (External Address): Feed new external call targets to EXTERNAL_PRECONDITION_AUDIT skill for address validation audit.