Smart Contract Architecture

Overview

All Ankara Chain contracts are written in Solidity ^0.8.24 and use OpenZeppelin upgradeable contracts (v5). They follow the UUPS proxy pattern — each deployed token is a lightweight ERC1967Proxy that delegates to a shared implementation.

packages/contracts-evm/
├── contracts/
│   ├── base/
│   │   ├── AnkaraChainBaseToken.sol      ← ERC-20 UUPS base (this page)
│   │   ├── AnkaraNFTBase.sol             ← ERC-721 UUPS base, see NFT Layer
│   │   ├── AnkaraMultiToken.sol          ← ERC-1155 UUPS base, see Multi-Token Layer
│   │   └── ManualOracle.sol              ← Reference price oracle
│   ├── interfaces/
│   │   ├── IIdentityVerifier.sol
│   │   ├── IAnkaraNFT.sol
│   │   ├── IAnkaraMultiToken.sol
│   │   └── IAnkaraOracle.sol
│   ├── templates/
│   │   ├── FarmlandToken.sol             ┐
│   │   ├── CommodityReceiptToken.sol     │ ERC-20 (6 templates)
│   │   ├── RealEstateToken.sol           │
│   │   ├── InvoiceToken.sol              │
│   │   ├── CarbonCreditToken.sol         │
│   │   ├── MiningRightsToken.sol         ┘
│   │   ├── FarmlandNFT.sol               ┐
│   │   ├── RealEstateNFT.sol             │ ERC-721 (4 templates)
│   │   ├── MiningRightsNFT.sol           │
│   │   ├── CommodityVaultNFT.sol         ┘
│   │   ├── CommodityBatchToken.sol       ┐ ERC-1155 (2 templates)
│   │   └── PoolVault.sol                 ┘
│   ├── escrow/
│   │   └── MilestoneEscrow.sol           ← Tranche-based escrow, see Escrow
│   └── factory/
│       ├── TokenFactory.sol              ← ERC-20 deploys
│       ├── NFTFactory.sol                ← ERC-721 deploys
│       ├── MultiTokenFactory.sol         ← ERC-1155 deploys
│       ├── EscrowFactory.sol             ← Escrow deploys
│       └── AnkaraFactoryRegistry.sol     ← Unified registry across all 4 factories
└── typechain-types/                       ← Auto-generated, gitignored

This page covers the ERC-20 base layer and the shared UUPS/factory patterns that every other layer follows. See NFT Layer, Multi-Token Layer, and Escrow for the layer-specific details.

AnkaraChainBaseToken

Abstract base contract inherited by all six templates. Provides:

ERC20Upgradeable — standard fungible token
ERC20PausableUpgradeable — halt transfers
ERC20BurnableUpgradeable — token burning
AccessControlUpgradeable — role-based permissions
UUPSUpgradeable — upgrade authorization

Storage slots (base)

bytes32 private _assetId;
string  private _countryCode;
AssetStatus private _status;         // DRAFT(0) → ACTIVE(1) → ...
IIdentityVerifier private _identityVerifier;
address public feeRecipient;
uint256[50] private __gap;           // Reserved for future upgrades

Roles

bytes32 public constant MINTER_ROLE   = keccak256("MINTER_ROLE");
bytes32 public constant PAUSER_ROLE   = keccak256("PAUSER_ROLE");
bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
bytes32 public constant MANAGER_ROLE  = keccak256("MANAGER_ROLE");

All roles are granted to admin_ at initialization. The admin also holds DEFAULT_ADMIN_ROLE and can delegate roles to other addresses.

Transfer Hook

Every mint, burn, and transfer passes through _update(), which checks the identity verifier for sender and receiver (when set):

function _update(address from, address to, uint256 amount) internal override {
    if (from != address(0) && address(_identityVerifier) != address(0)) {
        _checkVerified(from);
    }
    if (to != address(0) && address(_identityVerifier) != address(0)) {
        _checkVerified(to);
    }
    super._update(from, to, amount);
}

UUPS Proxy Pattern

Each token deploy creates a new ERC1967Proxy pointing to a shared implementation contract. This means:

Gas efficient — only one implementation bytecode on-chain, shared across all tokens of the same template
Upgradeable — the admin can upgrade the implementation to fix bugs without migrating token holders
Isolated state — each proxy has its own storage (balances, metadata, status)

Upgrade flow

TokenFactory.deployFarmlandToken(...)
  └─► new ERC1967Proxy(farmlandImpl, initData)
                          │
            FarmlandToken.initialize(...)
                          │
            Admin receives UPGRADER_ROLE
                          │
            Later: token.upgradeToAndCall(newImpl, "")
                          └─► requires UPGRADER_ROLE

TokenFactory

The factory stores implementation addresses and deploys proxies:

mapping(uint8 => address) public implementations;
// 0 = Farmland, 1 = Commodity, 2 = RealEstate, 3 = Invoice, 4 = CarbonCredit, 5 = MiningRights

The factory charges a deploymentFee in native tokens (covers deployment gas overhead and protocol revenue). The fee is configurable by the factory admin. Deploy event:

event TokenDeployed(
    uint8   indexed template,
    address indexed tokenAddress,
    address indexed deployer,
    bytes32 assetId,
    string  countryCode,
    uint256 timestamp
);

IIdentityVerifier

Pluggable KYC interface:

interface IIdentityVerifier {
    function isVerified(address account) external view returns (bool);
    function verifyIdentity(address account) external;
    function revokeIdentity(address account) external;
    function batchVerify(address[] calldata accounts) external;
}

Implement this interface with any KYC provider (Smile Identity, Persona, BVN/NIN, Ghana Card) and pass the contract address at deploy time.

WhitelistVerifier (reference implementation)

A simple on-chain whitelist ships with the contracts for development and testing:

// In tests
const verifier = await WhitelistVerifier.deploy(admin.address);
await verifier.verifyIdentity(userAddress);

// In deploy options
factory.deployFarmland({ ..., identityVerifier: verifier.address });

Running the Contracts Locally

cd packages/contracts-evm

# Compile
npm run compile

# Run tests (600 tests)
npm run test

# Deploy to local Hardhat node
npx hardhat node
npm run deploy:localhost

Security Notes

All contracts use OpenZeppelin’s audited upgradeable library (v5)
Storage gaps (uint256[50] private __gap) are reserved in both the base and each template for future storage additions without slot collisions
this.setStatus(...) is never called internally — templates use the internal _setStatus() to avoid RBAC bypass via external self-calls
Protocol fee is collected on deployment only — no ongoing fees on transfers

Getting Started

Stellar

CLI

Asset Templates

Smart Contracts

MCP Server

Smart Contract Architecture

Overview

AnkaraChainBaseToken

Storage slots (base)

Roles

Transfer Hook

UUPS Proxy Pattern

Upgrade flow

TokenFactory

IIdentityVerifier

WhitelistVerifier (reference implementation)

Running the Contracts Locally

Security Notes

​Overview

​AnkaraChainBaseToken

​Storage slots (base)

​Roles

​Transfer Hook

​UUPS Proxy Pattern

​Upgrade flow

​TokenFactory

​IIdentityVerifier

​WhitelistVerifier (reference implementation)

​Running the Contracts Locally

​Security Notes

Overview

AnkaraChainBaseToken

Storage slots (base)

Roles

Transfer Hook

UUPS Proxy Pattern

Upgrade flow

TokenFactory

IIdentityVerifier

WhitelistVerifier (reference implementation)

Running the Contracts Locally

Security Notes