Tortuga Estate

We express our gratitude to the Tortuga Estate team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

Tortuga TRWA is an ERC-3643 (T-REX) compliant security token platform, designed for tokenizing real-world real estate assets. The satellite token contract enforces Pattern A authorization for mint and burn operations via a dedicated authorisedSigner (an Internet Computer canister's Chain Fusion threshold ECDSA key), while forced transfers, wallet recovery, and freeze operations are delegated to the ERC-3643 agent role. A modular compliance layer enforces per-property regulatory rules such as jurisdiction restrictions, holding periods, investor categorization, holder caps, and sanctions/freeze checks.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• Functional requirements are detailed.

• • Project overview is detailed.

  • All roles in the system are described.

  • Use cases are described and detailed.

  • All futures are described.

• Technical description is detailed.

• • Run instructions are provided.

  • Technical specification is provided.

  • NatSpec is sufficient.

Code quality

• Common upstream contracts are reused through dependencies, but TokenVirtualPatched.sol vendors ERC-3643 code with documented minimal changes, which adds maintenance overhead.

• The development environment is configured.

Test coverage

Code coverage of the project is 83.70% (branch coverage).

• Deployment, initialization, minting, burning, transfers, freezing, recovery, governance, compliance modules, and basic user interactions are covered with tests.

• Negative cases coverage are present.

• Invariant testing is present for supply, frozen balances, nonce usage, pause state, and authority immutability.

• Interactions by several users are tested.

The architecture centers on TortugaTRWA, a UUPS-upgradeable ERC-3643 token that extends a vendored copy of the stock T-REX Token.sol (TokenVirtualPatched). The vendored base adds thirteen virtual keywords to enable override hooks in the child contract. TortugaTRWA replaces the stock agent-gated mint and burn with tortugaMint and tortugaBurn, which require a dedicated authorisedSigner address (the ICP canister's Chain Fusion ECDSA key) and enforce replay defenses via per-call nonce, chain ID, property ID, and expiry validation. Any token holder can burn their tokens through holderSelfBurn to redeem their position. A two-Safe governance topology separates pause authority (a 2-of-5 emergencyPauseSafe) from broad administrative authority (the 3-of-5 owner Safe), while compliance and identity-registry hot-swaps are gated by a 24-hour on-chain timelock that can be waived under a declared SEV-1 incident. Wallet recovery, forced transfers, and freeze operations are delegated to the ERC-3643 agent role, with compliance hooks made best-effort on emergency paths so that a reverting module cannot block agent authority.

The compliance subsystem is composed of six pluggable modules, all inheriting from AbstractTortugaModule (which itself extends Tokeny's AbstractModuleUpgradeable). Each module is deployed behind its own ERC-1967 UUPS proxy and wired to a stock Tokeny ModularCompliance contract. TortugaComplianceFactory orchestrates per-property deployment by instantiating a ModularCompliance proxy, selectively deploying each enabled module proxy, initializing configuration, binding modules, and transferring ownership to the specified _owner. Three modules are stateful (MaxHolderCountModule, PropertyHoldingPeriodModule, FinmaInvestorCategoryModule) and carry per-holder state keyed by compliance address; they expose migrateFrom and migrateForRecoveredWallet hooks so state survives compliance hot-swaps and wallet recoveries. Three modules are stateless (SanctionsFreezeModule, EligibleJurisdictionModule, MaxBalancePerHolderModule), reading their enforcement data from the bound token or identity registry at call time. Stateful modules use a migrationComplete gate that fails closed until explicitly marked by the owner, preventing a freshly-bound module from silently relaxing policy.

The system implements the ERC-3643 standard (ERC-20 with identity-registry-backed transfer restrictions and modular compliance checks). Upgradeable infrastructure relies on OpenZeppelin's UUPS proxy pattern and OwnableUpgradeable for ownership. The token's upgrade authority is restricted to the owner, and all modules block renounceOwnership to prevent permanent bricking of owner-gated configuration paths.

Files in Scope

TortugaTRWA.sol — The satellite ERC-3643 security token. Implements Pattern A authorization (tortugaMint, tortugaBurn gated by authorisedSigner), replay defenses (nonce, chainId, expiry, propertyId), a two-Safe pause topology, 24-hour timelocked compliance and identity-registry hot-swap with SEV-1 waiver, holder self-burn, best-effort compliance hooks on forced transfers and recovery, auto-migration of stateful modules during wallet recovery, and UUPS upgrade gating.

MaxHolderCountModule.sol — Stateful compliance module that caps the number of unique non-zero token holders per bound compliance. Tracks holder additions and removals via moduleMintAction, moduleTransferAction, and moduleBurnAction using the bound token's real balanceOf as the source of truth. Provides migrateFrom for compliance hot-swap state carry and migrateForRecoveredWalletFromToken for token-driven recovery migration. Enforces a migrationComplete gate that fails closed until the operator confirms state readiness.

TortugaComplianceFactory.sol — Deploys a per-property compliance stack in a single transaction. Instantiates a ModularCompliance proxy and up to six module proxies (sanctions, jurisdiction, holding period, holder count, max balance, FINMA category), initializes each with its configuration, wires modules to compliance via addModule, and transfers ownership of all contracts to the caller.

PropertyHoldingPeriodModule.sol — Stateful compliance module that enforces a minimum holding duration per holder. Records firstAcquired timestamps on mint and transfer receipt, blocks outbound transfers until the holding period elapses, and clears the record on full exit (burn-to-zero). Provides migrateFrom and migrateForRecoveredWalletFromToken for state migration during compliance hot-swaps and wallet recoveries. Enforces a migrationComplete gate and caps the configurable period at MAX_HOLDING_PERIOD (3,650 days).

FinmaInvestorCategoryModule.sol — Stateful compliance module restricting transfers by FINMA investor category (Retail, Qualified, Institutional). Assigns per-holder categories keyed by compliance address and checks a configurable sender-to-recipient policy matrix (allowedPair) on each transfer. Supports batch category assignment and owner-gated migration from a prior module instance via migrateFromPriorModule. Provides migrateForRecoveredWalletFromToken for token-driven recovery. Enforces a migrationComplete gate.

EligibleJurisdictionModule.sol — Stateless compliance module that restricts transfers to holders in whitelisted countries (ISO 3166-1 numeric codes). Reads each party's country from the bound token's identity registry via investorCountry and checks against a module-side eligibleCountry allowlist. Rejects country code 0 from ever being marked eligible, ensuring un-onboarded holders cannot transact.

MaxBalancePerHolderModule.sol — Stateless compliance module that caps each individual holder's token balance. The per-holder cap is keyed by compliance address, allowing different properties to have different limits. Uses the bound token's balanceOf at check time, accounts for self-transfers as a no-op, and exposes a maxBalance reader used by TortugaTRWA to emit RecoveryExceedsMaxBalance warnings.

SanctionsFreezeModule.sol — Stateless compliance module that delegates freeze enforcement to the bound token's own freeze state. Reads isFrozen and getFrozenTokens from the token via the compliance's getTokenBound accessor and rejects transfers where either party is fully frozen or the sender lacks sufficient unfrozen balance.

AbstractTortugaModule.sol — Abstract base contract for all Tortuga compliance modules. Extends Tokeny's AbstractModuleUpgradeable with a shared initializer (__TortugaModule_init), constructor-based initializer disabling for implementation contracts, renounceOwnership blocking, plug-and-play declaration, a virtual isStateful hook (defaults to false), and UUPS upgrade authorization gated to the owner.

TokenVirtualPatched.sol — Vendored copy of the upstream ERC-3643 Token.sol (v4.1.3) with thirteen virtual keywords added to enable overrides in TortugaTRWA. Provides the core ERC-20 token logic (transfer, approve, mint, burn), ERC-3643 compliance integration (identity registry checks, modular compliance hooks), agent-role gating, pause/unpause, address and partial-token freezing, forced transfers, and wallet recovery.

Privileged roles

TortugaTRWA.sol:

• owner (inherited from TokenVirtualPatched via AgentRoleUpgradeable / OwnableUpgradeable): The Main Admin Safe (3-of-5). Holds the broadest set of administrative powers.

• • Can call setAuthorisedSigner to rotate the canister-derived Chain Fusion ECDSA signer address (immediate, no timelock).

  • Can call setEmergencyPauseSafe to rotate the emergency pause Safe address.

  • Can call unpause to resume token operations after a pause.

  • Can call declareSev1 to waive the 24-hour timelock on the next compliance or registry swap.

  • Can call clearSev1 to revoke a previously declared SEV-1 waiver and retroactively reinstate the timelock on any in-flight pending swap.

  • Can call queueComplianceSwap to queue a new compliance contract for hot-swap with a 24-hour timelock (or immediate under SEV-1).

  • Can call cancelComplianceSwap to cancel an in-flight compliance hot-swap.

  • Can call executeComplianceSwap to finalize a timelocked compliance hot-swap.

  • Can call queueIdentityRegistrySwap to queue a new identity registry for hot-swap with a 24-hour timelock (or immediate under SEV-1).

  • Can call cancelIdentityRegistrySwap to cancel an in-flight identity registry swap.

  • Can call executeIdentityRegistrySwap to finalize a timelocked identity registry hot-swap.

  • Can call setOnchainID to update the token's OnchainID address.

  • Can call setName to update the token name (inherited from TokenVirtualPatched).

  • Can call setSymbol to update the token symbol (inherited from TokenVirtualPatched).

  • Can call transferOwnership to transfer contract ownership to a new address (inherited from OwnableUpgradeable).

  • Can call addAgent and removeAgent to manage the agent role set (inherited from AgentRoleUpgradeable).

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner.

  • renounceOwnership is explicitly blocked.

• authorisedSigner: The canister-derived Chain Fusion ECDSA address. The only address permitted to mint and burn tokens.

• • Can call tortugaMint to mint tokens to a verified address with replay-protected payload (nonce, chainId, propertyId, expiry).

  • Can call tortugaBurn to burn tokens from a holder's unfrozen balance with replay-protected payload.

• emergencyPauseSafe: A separate Safe (2-of-5) with pause-only authority.

• • Can call pause to halt all non-emergency token operations.

• agent (inherited from TokenVirtualPatched via AgentRoleUpgradeable): Addresses granted the agent role by the owner.

• • Can call forcedTransfer to execute emergency token transfers (court-ordered seizure, sanctions liquidation) with best-effort compliance hooks.

  • Can call recoveryAddress to recover tokens from a lost wallet to a new wallet, including auto-migration of stateful module state, identity re-registration, and freeze carry-forward.

  • Can call setAddressFrozen to freeze or unfreeze an address entirely.

  • Can call freezePartialTokens to freeze a specified amount of tokens for an address.

  • Can call unfreezePartialTokens to unfreeze a specified amount of tokens for an address.

  • Can call batchSetAddressFrozen, batchFreezePartialTokens, batchUnfreezePartialTokens, and batchForcedTransfer for batch operations (inherited from TokenVirtualPatched).

MaxHolderCountModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call setMaxHolderCount to update the maximum number of unique holders allowed.

  • Can call markMigrationComplete to unlock rule enforcement for a specific compliance binding.

  • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall modifier inherited from AbstractModuleUpgradeable): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction to update holder-count tracking after token state changes.

  • Can call migrateFrom to copy holder-set state from a prior module instance during compliance hot-swap.

  • Can call migrateForRecoveredWallet (deliberate no-op that emits RecoveryMigrationNoop; holder-count accuracy is maintained by moduleTransferAction via real-balance checks during the recovery's forced transfer).

• bound token (via require(msg.sender getTokenBound()) check): The token contract bound to the compliance.

• • Can call migrateForRecoveredWalletFromToken to trigger recovery-time tracked-balance migration from within the token's recoveryAddress flow.

TortugaComplianceFactory.sol:

• No privileged roles are retained by the factory post-deployment. The factory is a stateless deployer that transfers ownership of all created contracts (compliance and modules) to the _owner parameter during deployForProperty. Any address may call deployForProperty.

PropertyHoldingPeriodModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call setMinHoldingPeriod to update the minimum holding period (capped at MAX_HOLDING_PERIOD of 3,650 days).

  • Can call markMigrationComplete to unlock rule enforcement for a specific compliance binding.

  • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction to update per-holder acquisition timestamps and tracked balances.

  • Can call migrateFrom to copy holding-period state from a prior module instance during compliance hot-swap.

  • Can call migrateForRecoveredWallet to copy the lost wallet's holding-period clock to the new wallet during recovery.

• bound token (via require(msg.sender getTokenBound())): The token contract bound to the compliance.

• • Can call migrateForRecoveredWalletFromToken to trigger recovery-time holding-period migration from within the token's recoveryAddress flow.

FinmaInvestorCategoryModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call setHolderCategory to assign a FINMA investor category (Retail, Qualified, Institutional) to a holder under a specific compliance.

  • Can call batchSetHolderCategory to assign categories to multiple holders in a single transaction.

  • Can call setAllowedPair to configure the sender-to-recipient category policy matrix.

  • Can call markMigrationComplete to unlock rule enforcement for a specific compliance binding.

  • Can call migrateFromPriorModule to copy holder-category assignments from a previous module instance across compliance pairs.

  • Can call migrateForRecoveredWallet to copy the lost wallet's FINMA category to the new wallet during recovery.

  • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction (no-op hooks for compliance callback compatibility).

• bound token (via require(msg.sender getTokenBound())): The token contract bound to the compliance.

• • Can call migrateForRecoveredWalletFromToken to trigger recovery-time FINMA category migration from within the token's recoveryAddress flow.

EligibleJurisdictionModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call setCountryEligibility to enable or disable a country code in the jurisdiction allowlist (country code 0 can never be enabled).

  • Can call batchSetCountryEligibility to update eligibility for multiple country codes in a single transaction.

  • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction (no-op hooks for compliance callback compatibility).

MaxBalancePerHolderModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call setMaxBalance to set the per-holder token balance cap for a specific compliance binding.

  • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction (no-op hooks for compliance callback compatibility).

SanctionsFreezeModule.sol:

• owner (inherited from AbstractTortugaModule via AbstractModuleUpgradeable / OwnableUpgradeable): Module administrator.

• • Can call transferOwnership to transfer module ownership.

  • UUPS upgrade authority: _authorizeUpgrade restricts implementation upgrades to the owner (inherited from AbstractTortugaModule).

  • renounceOwnership is explicitly blocked (inherited from AbstractTortugaModule).

• compliance (via onlyComplianceCall): The bound compliance contract.

• • Can call moduleMintAction, moduleTransferAction, moduleBurnAction (no-op hooks for compliance callback compatibility).

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope