Lineage

Technical Documentation

Last updated on April 2, 2026

Overview

The LineageCoin smart contract suite provides modular, upgradeable, and audit-ready contracts for lineage tracking, land tokenization, inheritance automation, and the LGC utility token. All contracts use OpenZeppelin UUPS Upgradeable proxies.

Architecture

                    ┌─────────────────────────────────────────┐
                    │          LineageToken (LGC)              │
                    │  ERC-20 · Fees · Staking · Minting      │
                    └──────────────┬──────────────────────────┘
                                  │ collectFee()
              ┌────────────────────┼────────────────────┐
              ▼                    ▼                    ▼
   ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────┐
   │  LineageCore     │  │ PropertyRegistry │  │ VerificationRegistry│
   │  Lineage · Heirs │  │ ERC-721 · GIS   │  │ Verifiers · Claims  │
   │  Inheritance     │  │ IPFS Metadata   │  │ EIP-712 Signatures  │
   └────────┬─────────┘  └────────┬─────────┘  └─────────┬──────────┘
            │                     │                        │
            └──────────┬──────────┘                        │
                       ▼                                   │
            ┌──────────────────────┐                       │
            │   OracleConnector    │◄──────────────────────┘
            │   Off-chain Bridge   │
            │   Death · Docs · Gov │
            └──────────────────────┘

Contracts

LineageToken.sol

Standard: ERC-20 UUPS

LGC utility token — fees, staking, minting. Hard-capped at 100M tokens with configurable fee collection and MINTER_ROLE gated minting.

LineageCore.sol

Standard: UUPS

Lineage and heir registry with inheritance execution engine. Manages lineage creation, beneficiary assignment, and automated inheritance triggers. Routes all ownership changes through a strict hierarchical control model.

PropertyRegistry.sol

Standard: ERC-721 UUPS

Land tokenization linked to lineage IDs with IPFS metadata. Each property is minted as an ERC-721 NFT with geographic information system (GIS) data and off-chain document references stored via IPFS.

VerificationRegistry.sol

Standard: UUPS

Trusted verifier management with EIP-712 typed signature claims. Enables third-party verification of property ownership, identity, and legal status without on-chain gas costs.

OracleConnector.sol

Standard: UUPS

Off-chain data bridge — death confirmation, document submission, government API integration. Enables real-world events to trigger on-chain inheritance automation through verified oracle reports.

Event Schema

Event Parameters Usage
LineageCreated lineageId, owner Sync backend
Inherited lineageId, from, to Sync property & lineage
PropertyRegistered tokenId, lineageId Show new property
PropertyVerified tokenId Show verified status
InheritanceTriggered lineageId Backend updates & notifications
DeathConfirmed lineageId, confirmedBy Oracle relay
ClaimSubmitted claimId, subjectId, verifier Verification queue
OracleRequestFulfilled requestId, success, oracle Off-chain result

Security Features

  • UUPS Upgradeability — UPGRADER_ROLE gated, implementation validated
  • ReentrancyGuard — on all state-changing external functions
  • Pausable — emergency stop on all critical paths
  • AccessControl — granular roles: ADMIN, MINTER, ORACLE, VERIFIER, OPERATOR, UPGRADER
  • EIP-712 — typed signatures for verifier claims
  • Transfer Lock — properties locked during inheritance process
  • MAX_SUPPLY — hard cap on LGC at 100M tokens
  • Custom Errors — gas-efficient error handling

Roles Reference

Role Contract Capability
DEFAULT_ADMIN_ROLE All Grant/revoke roles
MINTER_ROLE LineageToken Mint LGC, collect fees
ORACLE_ROLE LineageCore Confirm death/inactivity
OPERATOR_ROLE PropertyRegistry, LineageCore Lock transfers, confirm heirs
VERIFIER_ROLE PropertyRegistry Verify properties
REGISTRY_ROLE VerificationRegistry Validate signatures externally
GOV_API_ROLE OracleConnector Create government API requests
UPGRADER_ROLE All Authorize upgrades

Use Cases

  • Digital Estate Planning: Register crypto wallets and digital assets, assign beneficiaries, and automate transfer on verified death or inactivity.
  • Real Estate Tokenization: Tokenize property as ERC-721 NFTs with GIS data and IPFS document storage for transparent, verifiable ownership.
  • Family Governance: Create multi-generational lineage trees with programmable inheritance rules and jurisdiction-aware compliance.
  • Business Succession: Automate transfer of business assets and ownership to designated successors based on verifiable conditions.

Fee Flow

User → approve(LineageCore, amount)
     → lineageCore.createLineage()
          → lgcToken.collectRegistrationFee(user)
               → transfer(user → feeCollector)

Fees are configurable by admin and flow directly to the feeCollector treasury address.

Deployment Order

  1. Deploy PropertyRegistry first
  2. Deploy LineageCore passing PropertyRegistry address
  3. Deploy LineageToken (utility token)
  4. Deploy VerificationRegistry
  5. Deploy OracleConnector

Integration Guide

To integrate with Lineage Token contracts:

  1. Install the contract artifacts: npm install @lineagecoin/contracts
  2. Import the interfaces and types for your target contracts
  3. Connect to the deployed contract addresses using your Ethereum provider
  4. Call createLineage() on LineageCore to register a new lineage
  5. Register properties via PropertyRegistry linked to the lineage ID
  6. Assign beneficiaries and configure inheritance rules

View the full source code on GitHub.