BlockRidge

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

BlockRidge is a comprehensive RWA ecosystem that provides compliant tokenization services, creating scalable and equitable access to financing opportunities for asset owners. It enables a broad range of users to invest in various asset classes through a compliant and streamlined interface.

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

Documentation quality

• Functional requirements are complete.

• • Project purpose is described.

  • Use cases are provided.

  • Project features are described.

  • Interactions are  described.

• Technical requirements are provided.

• • Run instructions are provided.

  • Technical specification is sufficient.

  • The NatSpec documentation is sufficient.

  • Authorization and roles are provided.

Code quality

• The development environment is configured.

Test coverage

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

• Deployment and basic user interactions are covered with tests.

• Interactions by several users are tested.

• Not all branches are covered with tests.

BlockRidge is a Real-World Asset (RWA) ecosystem designed to provide compliant tokenization services, facilitating financing opportunities for asset owners and offering investors access to a variety of asset classes through a regulatory-compliant interface. The platform's modular and scalable architecture comprises interconnected components that ensure compliance and flexibility across all operations.

At the core of BlockRidge is a compliance framework that enforces regulatory requirements by allowing dynamic configuration of rules tailored to specific jurisdictions or asset types. The platform also utilizes blockchain standards for identity management, maintaining a registry of verified identities and handling claims and attestations from trusted issuers, thereby ensuring that only compliant and verified users can participate in transactions.

BlockRidge offers escrow services for handling token deposits and settlements between users, supporting multiple stablecoins and administrative fee management. This provides flexible transaction mechanisms while maintaining compliance in financial operations. Additionally, the system enables the creation and management of funds, allowing asset owners to deploy new investment opportunities with specific parameters such as property type, valuation, and projected yield. It manages investment limits and financial metrics, supporting the compliant distribution of dividends to investors.

The tokenization module is responsible for creating and managing tokenized representations of real-world assets. By implementing compliance standards and handling token management, the platform ensures regulatory-compliant asset tokenization. BlockRidge also incorporates upgradeability mechanisms that allow contracts to be updated without changing their addresses, ensuring longevity and adaptability while maintaining continuous operation.

To ensure that only authorized entities can perform sensitive operations, the platform enforces role-based access controls. Key roles include owners, who control modules and perform administrative functions; agents, who execute operations such as settlements, identity verification, and token management; and compliance officers, who manage compliance modules and enforce regulatory adherence.

The modular design of BlockRidge promotes integration with other systems and adherence to protocols such as ERC-734, ERC-735, and ERC-3643. This ensures compatibility with various wallets, identity providers, and compliance services, fostering a versatile and interconnected ecosystem.

Files in Scope

• compliance/modular:

• • modules:

  • • AbstractModule.sol: Defines the base functionality for compliance modules, handling the binding and unbinding of compliance contracts. It includes modifiers to restrict function calls to bound compliance contracts only, establishing a secure link between the module and Modular Compliance.

    • AbstractModuleUpgradeable.sol: An upgradeable version of AbstractModule, implementing OpenZeppelin's upgradeability features. This contract is structured to allow compliance modules to be upgraded without disrupting the compliance binding status, which is maintained in a custom storage structure.

    • CountryAllowModule.sol: A compliance module that manages country-specific allowances, enabling or disabling token manipulation permissions for users based on their country. It facilitates adding or removing countries from the allowed list, ensuring jurisdictional compliance.

    • CountryRestrictModule: A compliance module that manages country-specific restrictions, enabling or disabling token manipulation permissions for users based on their country.

    • HoldTimeModule.sol: Compliance module that enforces a minimum hold period for tokens. Users cannot transfer tokens until the hold time has passed, ensuring adherence to time-based restrictions.

    • SupplyLimitModule.sol: Compliance module that restricts the total supply of tokens that can be minted for a given compliance contract, preventing excessive token issuance.

    • ModuleProxy.sol: A proxy contract based on the ERC1967 standard, used to manage upgradeable modules within the Modular Compliance architecture. It facilitates upgrading module implementations while preserving their state.

    • MaxBalanceModule.sol: Compliance module that restricts the maximum token balance each user can hold. It also allows pre-setting balances to ensure compliant behavior across accounts and manages identity-based balances for transfers and compliance checks.

    • IModule.sol: Interface defining the standard for all compliance modules. It includes functions for binding and unbinding compliance contracts, performing transfer, mint, and burn actions, and conducting compliance checks.

  • ModularCompliance.sol: The main contract for Modular Compliance, implementing IModularCompliance and inheriting OwnableUpgradeable and MCStorage. It allows the owner to bind/unbind tokens, add/remove modules, and manage module interactions while ensuring that token transfers comply with specified rules.

  • MCStorage.sol: Storage contract for the Modular Compliance system, holding the token bound to the compliance contract and the list of bound modules. It includes mappings to track the binding status of modules and a variable to manage the wrapper status.

  • IModularCompliance.sol: Interface defining the Modular Compliance contract, which manages compliance rules for token transfers by binding tokens and modules, adding/removing modules, and facilitating module interactions. It outlines functions for enforcing compliance and events to track module interactions.

• escrow:

• • EscrowController.sol: The main escrow contract managing token deposits and settlements for compliant users. It supports various stablecoins, applies an admin fee, and enables secure fund transfers for verified investors.

  • EscrowProxy.sol: A proxy contract for managing the upgradeability of the escrow implementation. It allows ownership control and maintenance mode, facilitating safe upgrades of the escrow contract.

  • EscrowStorage.sol: Storage contract for the escrow system, holding data such as admin wallet, admin fee, stablecoin mappings, and investor orders. It serves as the data layer for Escrow.sol to separate logic and storage.

  • IEscrowController: Interface for the EscrowController contract.

  • TransferHelper.sol: A utility library for safely interacting with ERC20 tokens and transferring ETH. It provides functions for safe approvals, transfers, and transferFrom operations, ensuring that token operations either succeed or revert.

• factory:

• • FactoryProxy.sol: A proxy contract for managing the upgradeability of the fund factory implementation. It includes basic authorization controls for ownership, allows the owner to upgrade the implementation, and enables maintenance mode for controlled operations.

  • FundFactory.sol: The main contract for creating funds and equity configurations. It interacts with proxy contracts to deploy and initialize new fund or equity configuration instances based on stored implementations. It also includes a batch whitelisting function for user identities.

  • FundFactoryStorage.sol: Storage contract for FundFactory, holding references to the main factory address, fund and equity configuration implementations, and proxy address. It serves as a data layer, separating storage from the factory logic in FundFactory.sol.

  • TREXFactory.sol: Main contract for deploying the TREX token suite, which includes identity registries, compliance modules, claim topics, and trusted issuer registries. It uses the CREATE2 opcode to predetermine deployment addresses, facilitating standardized deployments across EVM-compatible chains.

  • ITREXFactory.sol: Interface defining the TREX Factory contract's core functionalities for deploying and managing tokenization suite contracts. It includes data structures for token and claim details and function signatures for deploying tokens and setting up compliant infrastructure.

• fund:

• • EquityConfig.sol: A contract for managing equity configurations of a fund. It initializes parameters like minimum and maximum investment, valuation, projected yield, and Debt-to-Equity ratio. It allows authorized agents to update the fund's valuation.

  • EquityConfigStorage.sol: Storage contract for EquityConfig, holding data on fund name, Debt-to-Equity ratio, token address, and valuation metrics. This contract separates data storage from logic, supporting upgradeable architecture.

  • Fund.sol: The main contract for managing fund-related parameters and operations. It initializes with key details like property type, NAV (Net Asset Value), and projected yield. It allows token agents to update NAV, and distribute dividends in stablecoins to investors.

  • FundStorage.sol: Storage contract for Fund, holding key data like fund name, CUSIP, NAV, projected yield, and investment limits. This contract is used as a data layer for Fund.sol, maintaining the separation of storage from operational logic.

  • IFactory.sol: Interface for a factory contract, providing an external view of the factory owner's address. This is likely used to confirm authorization and ensure that only the owner can access certain functions.

  • IFund.sol: Interface for the Fund contract, providing a function signature for retrieving the Net Asset Value (NAV).

  • ITKN.sol: Interface for a token contract that includes functions to check if an address is an agent, get the token’s name, and retrieve its total supply. This interface is used in the Fund and EquityConfig contracts to validate agents and access token data.

• onchainID:

• • factory:

  • • IdFactory.sol: Main contract for managing the creation and linkage of on-chain identities (ONCHAINID) for both users and tokens. It allows the deployment of identity contracts using CREATE2 for deterministic addresses, linking and unlinking wallets to identities, and registering token factories authorized to create token identities.

    • IIdFactory.sol: Interface defining the core functions of the IdFactory, including creating identities, linking/unlinking wallets, adding/removing token factories, and providing view functions to retrieve linked identities, wallets, and token statuses.

  • interface:

  • • IClaimIssuer.sol: Interface for a claim issuer, allowing claim revocation and validation.

    • IERC734.sol: Interface defining ERC-734 standard functions for identity management, including key handling and execution approvals.

    • IERC735.sol: Interface defining ERC-735 standard functions for claim management within an identity, including claim addition, removal, and retrieval.

    • IIdentity.sol: Composite interface for both IERC734 (Key Holder) and IERC735 (Claim Holder), establishing a comprehensive identity standard.

    • IImplementationAuthority.sol: Interface for managing and retrieving the current implementation of a proxy, with upgrade capabilities.

  • proxy:

  • • IdentityProxy.sol: Acts as a proxy for the Identity contract. It delegates calls to an implementation contract whose address is managed by an ImplementationAuthority. This structure ensures that the proxy can dynamically update its implementation, enabling upgradability while maintaining the same address.

    • ImplementationAuthority.sol: Manages the current implementation address for the Identity proxy. It can be updated only by the owner, ensuring centralized control over the address of the actual implementation contract, which is beneficial for maintaining control over upgrades.

  • storage:

  • • Storage.sol: Contains the storage layout for the Identity contract, including mappings for keys, executions, and claims. This setup enables modular contract structure and compatibility with proxy-based upgradability. The _initialized and _canInteract flags control initialization status and interaction permissions.

    • Structs.sol: Defines data structures used across the identity system.

  • verifiers:

  • • Verifier.sol: Manages trusted issuers and required claim topics for identity verification, ensuring compliance by validating claims from approved sources.

  • version:

  • • Version.sol: Provides a simple versioning function that returns the version string of the implementation contract, allowing external parties to check which version of the contract logic is being used.

  • Identity.sol: Implements an ERC-734 "KeyHolder" and ERC-735 "ClaimHolder" identity contract that supports identity management, including key management for various roles (management, action, claim signer, and encryption). It allows the addition, execution, and management of claims and keys for each identity. This contract is intended to be deployed as an upgradable contract with modular storage, making it suitable for managing complex identity structures with separate, upgradeable logic.

  • ClaimIssuer.sol: This contract extends the Identity contract to provide claim issuance and revocation functionalities. It enables claim validation and revocation based on signatures, allowing the contract to check the validity and status of claims linked to identities.

• proxy:

• • authority:

  • • IAFactory.sol: Manages deployment of new instances of TREXImplementationAuthority, ensuring they are created by the authorized factory.

    • IIAFactory.sol: Interface defining IAFactory contract functions.

    • ITREXImplementationAuthority.sol: Interface defining TREXImplementationAuthority contract functions, including managing contract versions and associated addresses.

    • TREXImplementationAuthority.sol: Manages contract versions and maintains the current set of TREXContracts implementations used across the T-REX suite. Allows updating and fetching contract versions.

  • interface:

  • • IImplementationAuthority.sol: Interface providing a function to retrieve the current implementation address in use.

    • IProxy.sol: Interface for a proxy contract, allowing the setting and retrieval of the current implementation authority address.

  • AbstractProxy.sol: Abstract contract providing core proxy functions to delegate calls to an implementation authority.

  • ClaimTopicsRegistryProxy.sol: Proxy for the Claim Topics Registry, delegating calls to the appropriate logic contract set by the implementation authority.

  • IdentityRegistryProxy.sol: Proxy for the Identity Registry, initializing with registries and delegating to the implementation logic.

  • IdentityRegistryStorageProxy.sol: Proxy for storing identity data, initialized with implementation authority and delegates to the storage logic.

  • ModularComplianceProxy.sol: Proxy for the compliance module, which delegates all calls to the compliance logic contract.

  • ProxyV1.sol: A proxy contract allowing upgradeability and maintenance control, delegating calls to an implementation authority.

  • TokenProxy.sol: Proxy contract for token management, initialized with identity registry, compliance module, and token metadata, delegating to token logic.

  • TrustedIssuersRegistryProxy.sol: Proxy for the Trusted Issuers Registry, initialized with an implementation authority and delegating calls to the trusted issuers logic.

• registry:

• • implementation:

  • • ClaimTopicsRegistry.sol: Provides functionality to manage claim topics that are necessary for identity verification.

    • IdentityRegistry.sol: Manages user identities and verifies them based on trusted issuers and claim topics.

    • IdentityRegistryStorage.sol: Manages the storage of identities, including adding, modifying, and removing identities.

    • TrustedIssuersRegistry.sol: Manages trusted claim issuers and the topics they support.

  • interface:

  • • IClaimTopicsRegistry.sol: Interface for managing claim topics, allowing only the owner to add or remove claim topics.

    • IIdentityRegistry.sol: Interface for managing identities within the registry, including functions to register, update, and verify identities.

    • IIdentityRegistryStorage.sol: Interface defining storage management functions for identities, such as adding, removing, and updating stored identities.

    • ITrustedIssuersRegistry.sol: Interface for managing trusted claim issuers and associated claim topics, only callable by the contract owner.

  • storage:

  • • CTRStorage.sol: Provides internal storage for managing claim topics required for identity verification.

    • IRSStorage.sol: Manages identity-related data, specifically mapping between user addresses and identities (country and identity contract).

    • IRStorage.sol: Stores references to key registry contracts: Claim Topics Registry, Trusted Issuers Registry, and Identity Registry Storage.

    • TIRStorage.sol: Contains data structures for managing trusted issuers, including arrays and mappings for claim topics associated with each issuer.

• roles:

• • AgentRole.sol: Implements role-based access for agents and "TA" roles, allowing only the owner to assign and remove these roles.

  • AgentRoleUpgradeable.sol: Upgradeable contract version of AgentRole, also enabling role-based access for agents and "TA" roles, managed by the owner.

  • Roles.sol: Library providing internal functions to add, remove, and check roles for specific addresses.

• token:

• • Token.sol: Implements the token logic for minting, burning, transfers, and compliance checks. It integrates identity and compliance modules to enforce regulatory compliance.

  • TokenStorage.sol: Defines essential variables and mappings to manage ERC20 balances, allowances, and the token's freeze/pause status, along with identity and compliance contract references.

  • IToken.sol: Interface for the token contract, including functions for token management (freeze, pause, transfer) and linking identity and compliance registries.

  • VERC20.sol: Upgradeable ERC20 token contract, with basic initialization and restricted mint/burn functions.

• wrapper:

• • Wrapper.sol: Manages the creation and wrapping of ERC3643 tokens into ERC20 tokens, allowing for minting and burning to simulate a bridge between token standards.

  • WrapperStorage.sol: Provides storage structures for managing token wrappers, tracking mappings between ERC20 and ERC3643 tokens, and logging locked tokens.

Privileged roles

• ModularCompliance.sol:

• • Owner:

  • • Can bind or unbind tokens to the compliance contract.

    • Can add or remove modules, subject to module binding checks.

    • Authorized to call module functions and set the wrapper address.

  • Only Token (modifier):

  • • Ensures that only the token bound to the compliance contract can trigger certain functions, like transferred, created, and destroyed, which manage compliance checks for token actions.

• AbstractModule.sol:

• • onlyBoundCompliance (modifier):

  • • Restricts function access to only those compliance contracts that have been explicitly bound to this module.

  • onlyComplianceCall (modifier):

  • • Allows function calls exclusively from addresses associated with bound compliance contracts.

• AbstractModuleUpgradeable.sol:

• • Owner:

  • • Authorized to upgrade the module's implementation.

  • onlyBoundCompliance (modifier):

  • • Limits access to functions to bound compliance contracts.

  • onlyComplianceCall (modifier):

  • • Ensures only bound compliance contracts can invoke specific functions within this module.

• CountryAllowModule.sol:

• • Owner (through onlyComplianceCall modifier):

  • • Permitted to batch allow or disallow countries, and to individually allow or disallow countries for token manipulation.

  • onlyComplianceCall (modifier):

  • • Limits function calls for managing country allowances to bound compliance contracts, ensuring that only authorized compliance contracts can enforce these restrictions.

• HoldTimeModule.sol:

• • onlyComplianceCall (modifier):

  • • Ensures that only the compliance contract bound to this module can set the hold time for tokens.

  • Owner:

  • • Authorized to set or update the hold time for tokens, enforcing transfer restrictions based on the specified period.

• SupplyLimitModule.sol:

• • onlyComplianceCall (modifier):

  • • Limits the ability to set the supply limit to the bound compliance contract, safeguarding against unauthorized adjustments.

  • Owner:

  • • Permitted to define the maximum supply limit, capping token issuance to prevent oversupply.

• MaxBalanceModule.sol:

• • onlyComplianceCall (modifier):

  • • Allows only the compliance contract bound to this module to set or modify maximum balances, ensuring authorized access.

  • Owner (only compliance owner can access):

  • • Can set maximum balance limits and pre-set balances for specific identities.

    • Authorized to complete the preset configuration for a compliance contract, allowing it to bind with the module.

• Escrow.sol:

• • Owner:

  • • Can set the admin fee and admin wallet.

    • Authorized to rescue any ERC20 tokens from the contract except for pending amounts in stablecoins.

  • Agent:

  • • Can perform the settlement function, finalizing an order and transferring the amount to themselves and the admin wallet (less the admin fee). Ensures that only authorized agents can complete settlements.

• EscrowProxy.sol

• • Proxy Owner (modifier onlyProxyOwner):

  • • Controls upgradeability by authorizing changes to the escrow implementation.

    • Can enable or disable maintenance mode, restricting certain operations during maintenance.

    • Can transfer proxy ownership to a new owner, ensuring controlled access over upgradeability and management functions.

• FactoryProxy.sol:

• • Proxy Owner (modifier onlyProxyOwner):

  • • Controls upgradeability by authorizing updates to the factory implementation.

    • Can enable or disable maintenance mode, restricting operations during maintenance.

    • Has the authority to transfer proxy ownership, ensuring controlled management over the factory upgradeability.

• FundFactory.sol:

• • Owner (determined by masterFactory owner):

  • • Authorized to set fund and equity configuration implementations.

    • Permitted to create new fund and equity configuration contracts, ensuring only the factory owner can deploy new configurations.

  • Agent:

  • • Can perform batchWhitelist for bulk registration of user identities within an identity registry associated with a token, provided they are registered as an agent within the registry.

• TREXFactory.sol:

• • Owner:

  • • Authorized to deploy a new TREX token suite using deployTREXSuite, allowing comprehensive setup of identity, compliance, and registry components for a compliant token ecosystem.

    • Can set or update the implementationAuthority and idFactory, ensuring that only authorized individuals can control core components related to token implementations and identity management.

    • Has exclusive access to recoverContractOwnership, which is typically used to transfer ownership of contracts previously owned by the factory, such as the Identity Registry Storage (IRS).

  • Agent (within Identity Registry and Token context):

  • • The owner can add agents to the Identity Registry and Token, giving agents permission to perform functions related to identity verification and token management as required.

• EquityConfig.sol:

• • Factory:

  • • Initializes the contract with key fund parameters like minimum investment, maximum investment, and valuation metrics.

  • Token Agent:

  • • Authorized to update the fund's valuation by calling setValuation, ensuring that only designated agents can alter financial metrics of the fund.

• Fund.sol

• • Factory:

  • • Initializes the fund with key parameters such as NAV and investment limits.

  • Token Agent:

  • • Can update the NAV using setNAV, ensuring that only authorized agents can make adjustments to the fund's asset valuation.

    • Authorized to distribute dividends to a list of investors using shareDividend, allowing controlled and compliant distribution of fund proceeds.

• Identity.sol

• • Management Key Holders:

  • • Management key holders can perform actions such as executing transactions, adding and removing keys, approving executions, and modifying claims within the identity.

    • Management key holders can also directly interact with the identity contract for actions that affect the identity as a whole, including the execution of internal transactions.

  • Action Key Holders:

  • • Action key holders can initiate external calls through the execute function. These keys have lower permissions than management keys and are intended for actions that do not modify the state of the identity.

  • Claim Key Holders:

  • • Claim key holders are authorized to add and remove claims on behalf of the identity. They can issue claims to other identities and sign claims to validate user assertions within the addClaim and removeClaim functions.

  • Encryption Key Holders:

  • • Encryption key holders manage data encryption, useful for holding claims or sensitive identity data securely. These keys are primarily used in contexts that require identity data to be encrypted before storage or transmission.

• ClaimIssuer.sol

• • Manager (Identity Management Key):

  • • The onlyManager modifier restricts claim revocation functions to only be called by accounts with a management key. Managers can revoke claims by their ID or revoke signatures, maintaining control over the status of each claim.

    • Managers can also check the validity of claims through isClaimValid, ensuring a robust verification process.

  • Claim Signers (Claim Key):

  • • Claim signers are authorized to verify claims based on their signatures using the isClaimValid function, provided they have valid claim keys.

• Verifier.sol:

• • Owner:

  • • Has authority to add and remove trusted issuers, manage required claim topics, and update claim topics for trusted issuers.

• AbstractProxy.sol:

• • Implementation Authority:

  • • Only the current implementation authority can set a new implementation authority address.

• ProxyV1.sol:

• • Proxy Owner:

  • • Can transfer proxy ownership, toggle maintenance mode, upgrade implementation, and upgrade with initialization call.

• IAFactory.sol:

• • TREX Implementation Authority:

  • • Only the reference implementation authority can deploy a new instance of TREXImplementationAuthority through this factory.

• TREXImplementationAuthority.sol:

• • Owner:

  • • Can add new T-REX contract versions, set the TREXFactory and IAFactory addresses, and update the active version used by proxies.

  • Token Owner:

  • • Only the token's owner can change the implementation authority for all linked contracts, including token proxies, registries, and compliance modules.

• ClaimTopicsRegistry.sol:

• • Owner:

  • • Can add or remove claim topics necessary for identity verification.

• IdentityRegistry.sol:

• • Owner:

  • • Can set the addresses of the Identity Registry Storage, Claim Topics Registry, and Trusted Issuers Registry.

  • Agent:

  • • Can register, update, and delete identities.

    • Can update the country of residence for an identity.

• IdentityRegistryStorage.sol:

• • Owner:

  • • Initializes the contract and binds Identity Registries.

  • Agent:

  • • Can add, modify, and remove identities in storage.

    • Can modify investor country information.

• TrustedIssuersRegistry.sol:

• • Owner:

  • • Can add, remove, or update trusted issuers and their associated claim topics.

• AgentRole.sol / AgentRoleUpgradeable.sol:

• • Owner:

  • • Can assign and remove both "Agent" and "TA" roles, providing privileged access to designated accounts.

  • Agent:

  • • Granted permissions to execute functions restricted to the "Agent" role.

  • TA:

  • • Granted permissions to execute functions restricted to the "TA" role and participate in actions alongside "Agent" role holders.

• Token.sol:

• • Owner:

  • • Authorized to initialize the token, set token information (name, symbol, onchain ID), configure Identity Registry and Compliance contracts, and manage ownership.

  • Agent:

  • • Permitted to pause/unpause the token, freeze/unfreeze addresses and tokens, recover addresses, and enforce transfers, minting, and burning.

  • Agents (TAs):

  • • Can perform partial token freezes and unfreezes and are allowed in certain transfer operations that require compliance with token policies.

• VERC20.sol:

• • Owner:

  • • Authorized to mint and burn tokens, restricted to only the owner for controlled token supply management.

• Wrapper.sol:

• • Owner:

  • • Has authority to set the on-chain ID for the wrapper.

  • Agents (in ERC3643):

  • • Only agents associated with the ERC3643 token can create a wrapped ERC20 token through the createWrapToken function, ensuring controlled access to the wrapping process.

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

Assets in Scope