Contract Descriptions

This document provides an overview of each contract and its role in the Colle ecosystem.

---

MarketHub

1. MarketHub

MarketHub is the central contract of the Colle marketplace system. It serves as the single source of truth for all modules in the system, implementing and inheriting every registry in the system.

Key Features:

• Core Assignment: In its constructor, MarketHub assigns the UpgradeGatekeeper, EscrowUpgradeable, and VaultUpgradeable. Being a non-upgradeable contract, it ensures that these crucial contracts cannot be substituted, thereby fortifying the security of the system.

• Helper Logic: MarketHub provides additional helper logic for its modules. It maintains track of the minimum USDC price at which a sale can be created. It also notifies registered markets when ownership of an item changes.

• Control of Sales: MarketHub has the ability to pause or resume new sales within the system. This is an essential feature that provides the flexibility to manage the marketplace based on various situations or needs.

Non-Upgradeability:

The MarketHub contract is non-upgradeable. This intentional design choice ensures the immutability of core contracts in the system, providing a robust foundation for the marketplace.

2. MarketHubRegistrar & MarketHubRegistrarUpgradeable

MarketHubRegistrar and MarketHubRegistrarUpgradeable are two parent classes that implement the IMarketHubRegistrar interface. They inherit from MarketAccess and MarketAccessUpgradeable respectively, granting "onlyRelayer" and "onlyAdmin" modifiers to the inheriting contracts. These classes offer functions for registering and unregistering from the marketplace and are inherited by various modules of the system.

Key Features:

• Interface for Registration: Both classes provide an interface for modules to be registered within the Colle marketplace. This provides a standardized method for integrating new components into the system.

• Access to MarketHub: Once a module is registered, it inherits a reference to MarketHub. This reference grants it the ability to traverse the singleton and interact with other modules in the system, enhancing the system's interconnectivity and efficiency.

• Colle Access Control: By inheriting from MarketAccess and MarketAccessUpgradeable, these classes provide "onlyRelayer" and "onlyAdmin" modifiers to the inheriting contracts. This ensures that certain functions can only be called by a caller with the appropriate role, enforcing a layer of security within the system.

Upgradeability:

The upgradeability feature of MarketHubRegistrarUpgradeable comes as a result of inheriting from MarketAccessUpgradeable, which uses OpenZeppelin's AccessControlUpgradeable. Due to some modules using constructors and others using initializers, we opted to split this role into two sibling contracts: MarketHubRegistrar and MarketHubRegistrarUpgradeable. This flexibility in handling upgrades allows for future enhancements and functional improvements.

---

Collections

1. CollectionRegistry

CollectionRegistry is a base contract that MarketHub inherits from. It manages which collections are allowed to be traded on the marketplace. Notably, only ColleCollections can be traded due to the overriding of the transfer function implemented in the ColleCollection contract.

Key Responsibilities:

• Registers and Unregisters Collections: Manages the registration and unregistration of collections in the Colle system. Only the entities assigned the Colle role can register or unregister collections.

• Tracks Registered Collections: Maintains a mapping from collection addresses to their registration status. This allows for easy look-up of whether a collection is registered and eligible to be traded.

• Provides Collection Interface: It can return the interface for a registered collection. This is required to interact with the collection in a standard manner.

2. ColleCollection

ColleCollection is an ERC721 collection that is tradable on the marketplace. It represents physical goods in the form of digital assets.

Key Responsibilities:

• Tracks Sale Metadata: Prior to any token sale on the marketplace, the sale metadata needs to be set. The metadata contains an IPFS hash that maps to the current condition of the physical good at the time of sale. This is critical for dispute resolution, especially when discrepancies arise between the listed and received conditions of an item.

• Prevents Unintentional Transfers: To ensure the secure handling of tokens representing physical goods, standard ERC721 transfer functions have been deliberately broken and re-introduced. This breaks compliance with the ERC721 standard to prevent unintentional transfers through third-party marketplaces, while still permitting manual gifting of the items when required.

• Supports EIP-712 Style Permit Functions: To provide a user-friendly experience and facilitate gasless transactions for our users, the contract incorporates EIP-712 style permit functions. This allows actions such as approval and transfers to be relayed.

---

Currencies

1. CurrencyRegistry

The CurrencyRegistry contract acts as a base contract inherited by the MarketHub contract. Its main function is to maintain a two-way mapping between the registered BaseCurrencies and their corresponding ERC20 tokens.

Key Responsibilities:

• Token Tracking: It keeps track of all ERC20 tokens that are registered in the marketplace, correlating each one with their respective BaseCurrency.

• Currency Validation: The marketplace only accepts those ERC20 tokens that have been registered in this registry. It ensures that only recognized tokens are used in transactions across the marketplace.

2. BaseCurrency

The BaseCurrency contract serves as a parent contract that abstracts any ERC20 token registered on the marketplace. It's designed to facilitate the management and conversion of various ERC20 tokens within the Colle ecosystem.

Key Responsibilities:

• Token Reference: This contract stores a reference to the specific ERC20 token that is registered on the marketplace.

• Balance Conversion: It contains a helper function that aids in converting a balance of the specific ERC20 token into an equivalent value in USDC (USD Coin).

• Price and Royalty Calculations: The USDC equivalent value derived from the conversion is utilized in the calculation of royalties and in ensuring that sales meet a minimum USDC value price.

3. USDCCurrency

USDCCurrency is a contract that inherits from the BaseCurrency contract. Its primary purpose is to maintain a reference to the USDC token and facilitate the conversion of its ERC20 units value to an equivalent USDC value.

Key Features:

• USDC Reference: It keeps track of the USDC token, allowing for easy reference when performing conversions and operations within the marketplace.

• Conversion: Since USDC is a stablecoin pegged to the US dollar, no actual conversion process is necessary. Therefore, any function that attempts to convert from USDC ERC20 units to a USDC value will simply return the value given.

---

Markets

1. MarketRegistry

MarketRegistry is a parent contract of MarketHub and functions as a registry for market contracts within the Colle system.

Market contracts serve a vital role in the platform as they facilitate the creation of sales within the EscrowUpgradeable contract.

Key Features:

• Market Storage: Markets are stored via a keccak256 hash of the market's name, which provides a secure and efficient way to handle market data.

• Market Retrieval: Markets can be easily fetched using their respective hashed name, providing straightforward access to market data.

• Iterative Functionality: The MarketRegistry tracks these hashed market names in an array. This functionality allows other components in the system to iterate over all markets when necessary, providing extensive accessibility to the market data.

2. BaseMarketUpgradeable

BaseMarketUpgradeable serves as the parent contract for all registered markets on the platform. It is designed to facilitate the creation of new sales and offers a _createSale internal function for its children contracts to utilize.

Upgradeable Nature: Despite not all markets requiring upgradeability, BaseMarketUpgradeable was built with upgradeability as a core feature. The motivation behind this design choice lies in the need for preserving intermediate data about potential sales. If we were to update these features by replacing the contract with a new module, this data would be lost. As a solution, we opted to make the contracts UUPS upgradeable.

Risk Mitigation: We acknowledge the potential risk involved in allowing contracts to be upgradeable as it might present attack vectors. In order to mitigate this risk, upgrades have been gated to only implementations that are approved by the UpgradeGatekeeper contract. Initially, the ownership of the UpgradeGatekeeper is held by a Colle multisig, but it is planned to be moved to a DAO in the future for enhanced decentralization and security.

3. ListingMarketUpgradeable

The ListingMarketUpgradeable contract inherits from BaseMarketUpgradeable and acts as a marketplace where sellers can list items for sale at a specified price and in a specific ERC20 currency. The act of purchasing an item from the listing automatically triggers the creation of a sale within the escrow system.

Key Features:

• Sales Creation: The purchase of an item from the market initiates the creation of a new sale in the escrow system.

• Payment Flexibility: The contract provides buyers with three payment options to choose from:

  • On-Chain Payments: This option creates a sale with the AwaitingERC20Deposit state, providing the buyer a 24-hour window to make the payment.

  • Off-Chain Payments: This option creates a sale with the AwaitingSettlement state and assigns Colle as the spender. The transaction can only continue once Colle confirms the off-chain payments have been settled.

• Gasless Interactions: The contract employs EIP-712 permit-style functions, allowing users to interact with the system without incurring gas costs.

4. OfferMarketUpgradeable

The OfferMarketUpgradeable contract inherits from BaseMarketUpgradeable and provides a marketplace where buyers can place offers to purchase items for a specified price and ERC20 currency. Sellers can then choose to accept these offers, triggering the creation of a sale within the escrow system.

Key Features:

• Offer Creation and Acceptance: Buyers can place offers for items using specific prices and ERC20 currencies. Sellers can review these offers and choose to accept them, automatically initiating the creation of a sale within the escrow system.

• Payment Flexibility: The contract provides buyers with three payment options to choose from:

  • On-Chain Payments: This option creates a sale with the AwaitingERC20Deposit state, providing the buyer a 24-hour window to make the payment.

  • Off-Chain Payments: This option creates a sale with the AwaitingSettlement state and assigns Colle as the spender. The transaction can only continue once Colle confirms the off-chain payments have been settled.

• Gasless Interactions: The contract employs EIP-712 permit-style functions, allowing users to interact with the system without incurring gas costs.

---

Escrow

1. IEscrowRegistry

The IEscrowRegistry interface is implemented by the MarketHub and is responsible for fetching the assigned escrow for a given market.

Key Points:

• The IEscrowRegistry does not support functions for registering or unregistering an escrow. Once an escrow is assigned, it is a permanent assignment and cannot be changed.

This design choice provides stability and ensures that once an escrow process is set, it cannot be altered, enhancing the integrity and trustworthiness of the system.

2. EscrowUpgradeable

The EscrowUpgradeable contract manages the escrow system for the marketplace. This contract provides an interface for the trade of ERC721 tokens and ERC20 tokens and is designed using the Universal Upgradeable Proxy Standard (UUPS) for upgradeability.

Key Features:

• Regulated Sale Creation: Only markets registered within the system can create sales in the Escrow.

• Real-World Logistics Handling: Given that the Colle marketplace deals with mirrored assets, the Escrow system must account for the shipping and handling of the physical goods. This involves real-world logistics, which may lead to potential complications. To manage this, a state machine is implemented.

• Deposit & Withdrawal System: When a sale begins, both the ERC20 and ERC721 tokens are deposited into the vault. Upon the conclusion of the sale, these tokens are withdrawn and distributed to the respective parties. The recipients of the tokens are determined based on the exit state of the sale.

• Sale Updates: The state of a sale can be updated by either the buyer, the seller, or Colle. The ability to update depends on the current state of the sale and the state the actor intends to transition to.

• On-Chain vs Off-Chain Payments: The escrow is aware that some sales are started off-chain, in which case it adjusts its expectations. For on-chain payments, the full price of the sale and taxes are expected to be in escrow. For off-chain payments, only enough USDC to cover the royalties, comission and taxes are required to be in escrow.

• Vault Management: This contract also oversees the management of the vault, which holds the funds and the NFT during the escrow period. This ensures secure handling and storage of the assets involved in a transaction.

• Gasless Interactions: The contract employs EIP-712 permit-style functions, allowing users to interact with the system without incurring gas costs.

Upgradeability:

The EscrowUpgradeable contract is designed to be upgradeable using the Universal Upgradeable Proxy Standard (UUPS). This allows the flexibility of updating the state machine should more states, or more state transitions, be needed in the future.

While there are risks associated with allowing upgrades due to the potential of a malicious upgrade that could be an attack vector, we have introduced countermeasures to mitigate this risk. The upgrades are gated and only implementations approved by the UpgradeGatekeeper contract are allowed. The ownership of UpgradeGatekeeper is initially owned by a Colle multisig, but it is planned to be moved to a Decentralized Autonomous Organization (DAO) in the future. This provides additional security and confidence in the integrity of the marketplace system.

The EscrowUpgradeable contract is, therefore, a critical component of the Colle marketplace, handling the secure and efficient exchange of physical goods represented as NFTs, and facilitating the smooth operation of the marketplace.

---

Vaults

1. IVaultRegistry

The IVaultRegistry interface is implemented by the MarketHub contract, and provides functionalities related to the fetching of the system's vault.

Key Features:

• Vault Fetching: This interface allows other components of the platform to fetch the reference to the vault. The vault plays a crucial role in the platform by securely holding the ERC20 and ERC721 tokens while they are in escrow during a transaction.

• Singleton Vault: Given that there is only one vault in the system, the IVaultRegistry does not provide functions for registering or unregistering vaults.

2. VaultUpgradeable

The VaultUpgradeable contract manages the assets of the Colle marketplace while they are in escrow. It provides a safe storage mechanism for both ERC20 and ERC721 tokens during the trade process.

Key Features:

• Asset Deposit and Withdrawal: The contract provides deposit and withdrawal functions for both ERC20 and ERC721 tokens. These operations are exclusively callable by the Escrow to ensure the security of the transactions.

• On-Chain vs Off-Chain Payments: The vault is aware that some sales are started off-chain, in which case it adjusts its expectations. For on-chain payments, the full price of the sale and taxes are expected to be in escrow, and thus in the vault. For off-chain payments, only enough USDC to cover the royalties, comission and taxes are required to be in escrow/the vault.

• Off-Chain Payouts: The vault is aware some users may want to be paid off-chain, rather than on-chain. It offers functions for sellers to opt-in to off-chain payouts. In the event of this, the seller is forfeiting their payout to Colle's commissions address, and emitting a OffchainPayout event, notifying Colle that the seller is owed money off-chain.

• IERC721Receiver Implementation: The VaultUpgradeable contract implements the IERC721Receiver interface to safely receive ERC721 tokens. However, it only accepts tokens if it is the designated operator. This is due to the fact that tokens should only be received when deposited via the Escrow, in which case the vault acts as the operator.

• Gasless Interactions: The contract employs EIP-712 permit-style functions, allowing users to interact with the system without incurring gas costs.

Upgradeability:

This contract uses the UUPS upgradeability pattern. This allows for flexibility in future updates, such as supporting additional token standards or enabling deposited funds to earn interest by integrating with lending protocols like AAVE.

Despite the inherent risks associated with upgradeability, Colle has implemented countermeasures to mitigate potential threats. Upgrades are regulated and can only be executed using implementations approved by the UpgradeGatekeeper contract. Initially, a Colle multisig owns the UpgradeGatekeeper, but plans are in place to transfer ownership to a Decentralized Autonomous Organization (DAO) in the future, further ensuring the security and integrity of the system.

The VaultUpgradeable contract is a key component in ensuring the secure and efficient operation of the Colle marketplace's escrow system.

---

KYC

1. KYCRegistry

The KYCRegistry contract is a component inherited by MarketHub that encapsulates the functionality needed for managing KYC (Know Your Customer) verified accounts within the Colle system.

Key Features:

• Account Registration: Colle has the ability to register accounts that have successfully completed a KYC process. The account is also assigned a tier upon registration.

• Tier Assignment: The assigned tier corresponds to a royalty tier. Upon the completion of a sale, this tier is used to determine the corresponding BaseRoyalty contract. This contract is then used to calculate the royalty and commission amounts that apply to the sale.

• Tier Updates: Tiers can be updated over time to reward high-quality sellers within the system. This mechanism encourages seller performance and maintains a high standard of operation within the marketplace.

• Account Management: In addition to these functionalities, the KYCRegistry contract provides Colle with the capability to halt or ban accounts. This functionality can be used to prevent certain accounts from creating new trades, providing an additional layer of security and control within the marketplace.

2. Account

The Account struct is a key component within the KYC (Know Your Customer) process of the Colle system. An Account struct is assigned to each account that successfully completes the KYC process.

Key Components of the Account Struct:

• Address: This tracks the address of the KYC-verified account.

• Tier: This is the assigned royalty tier of the account, which is used to determine the royalty and commission amounts applied to the sales of the account.

• Account Status: The status of the account is tracked, providing information about the account's current operational state. This could reflect whether the account is active, halted, or banned.

---

Royalties

1. RoyaltyRegistry

The RoyaltyRegistry contract is a parent contract of MarketHub and provides a registry for managing BaseRoyalty contracts.

Key Features:

• Royalty Contract Registration: This contract enables the registration and unregistration of BaseRoyalty contracts. This is critical for keeping track of all active royalty contracts within the system.

• RoyaltyPool Contract Registration: The RoyaltyRegistry contract allows for a one-time registration of the RoyaltyPool contract. This registration process is crucial as it defines where the royalty payments will be directed.

• Commission Address Registration: The contract also allows for the one-time registration of the Colle commissions address. All commission payments will be directed to this address.

2. RoyaltyPool

The RoyaltyPool contract manages the pool of previous owners eligible to receive royalties. This pool includes the initial owner of the token as well as recent owners.

Key Features:

• Tracking Initial Sellers: The contract enables the EscrowUpgradeable contract to track an initial seller of a token, if none had been set. This individual will permanently receive royalties and will not be rotated out of the pool.

• Tracking New Owners: The RoyaltyPool contract allows the EscrowUpgradeable contract to keep track of new owners. The pool can contain up to four individuals at a time, meaning each previous owner in this pool will receive a portion of the royalties for the subsequent four sales, after which they will be rotated out of the pool.

• Helper Functions for Royalty Calculations: The contract provides several helper functions for calculating royalties. These include functions to determine the total shares of the pool, fetch the recent owners, fetch the initial owner, and ascertain the weight of the initial owner.

By managing the pool of previous owners and providing functionalities for royalty calculations, the RoyaltyPool contract plays a critical role in the fair distribution of royalties within the Colle marketplace.

3. BaseRoyalty

BaseRoyalty is the parent contract for all royalty implementations within the Colle marketplace. It provides abstract functions that its children contracts must implement to handle the calculation of royalty and commission rates based on respective tiers.

Key Features:

• Abstract Functions for Royalty and Commission Rates: The contract provides two abstract functions. The children contracts must implement these functions to calculate the basis points (a basis point is one hundredth of a percentage point) associated with the royalty and commission rates for a given royalty tier.

• Breakdown of Royalty and Commission: The contract also offers a function that calculates the breakdown of royalty and commission. Given an ERC20 token and amount, this function determines the portion of that amount to be allocated to the royalty pool and commission. The breakdown is based on the basis points returned by the functions implemented by the children contracts.

• Basis Points Interpretation: The basis points are out of 10,000. For instance, if a child contract returns 100 as its basis points for the royalty pool, it means 1% of the funds would be paid out to the royalty pool.

4. GreenTierRoyalty

GreenTierRoyaltyV1 is an implementation of the BaseRoyalty contract specifically designed for the green tier, the default tier for basic collectors. This tier is associated with the highest percentage fees on the platform.

Key Features:

• Tier-Specific Royalty Calculation: The GreenTierRoyalty contract implements a tiered approach to calculate the royalties, which varies based on the value of the sale. It defines different rates for sales that are less than $1000, less than $10,000, and greater than $10,000.

• Adherence to BaseRoyalty Structure: Like all royalty contracts, GreenTierRoyalty inherits from BaseRoyalty and implements its abstract functions. This ensures consistency in the calculation and handling of royalties across different tiers.

5. GoldTierRoyalty

GoldTierRoyaltyV1 is an implementation of the BaseRoyalty contract specifically designed for the gold tier. This tier is associated with the highest percentage fees on the platform.

Key Features:

• Tier-Specific Royalty Calculation: The GoldTierRoyalty contract implements a tiered approach to calculate the royalties, which varies based on the value of the sale. It defines different rates for sales that are less than $1000, less than $10,000, and greater than $10,000.

• Adherence to BaseRoyalty Structure: Like all royalty contracts, GoldTierRoyalty inherits from BaseRoyalty and implements its abstract functions. This ensures consistency in the calculation and handling of royalties across different tiers.

6. PlatinumTierRoyalty

PlatinumTierRoyaltyV1 is an implementation of the BaseRoyalty contract specifically designed for the platinum tier. This tier is associated with the highest percentage fees on the platform.

Key Features:

• Tier-Specific Royalty Calculation: The PlatinumTierRoyalty contract implements a tiered approach to calculate the royalties, which varies based on the value of the sale. It defines different rates for sales that are less than $1000, less than $10,000, and greater than $10,000.

• Adherence to BaseRoyalty Structure: Like all royalty contracts, PlatinumTierRoyalty inherits from BaseRoyalty and implements its abstract functions. This ensures consistency in the calculation and handling of royalties across different tiers.

7. BlackTierRoyalty

BlackTierRoyaltyV1 is an implementation of the BaseRoyalty contract specifically designed for the platinum tier. This tier is associated with the highest percentage fees on the platform.

Key Features:

• Tier-Specific Royalty Calculation: The BlackTierRoyalty contract implements a tiered approach to calculate the royalties, which varies based on the value of the sale. It defines different rates for sales that are less than $1000, less than $10,000, and greater than $10,000.

• Adherence to BaseRoyalty Structure: Like all royalty contracts, BlackTierRoyalty inherits from BaseRoyalty and implements its abstract functions. This ensures consistency in the calculation and handling of royalties across different tiers.

---

Upgrade Gatekeeper

1. UpgradeGatekeeper

The UpgradeGatekeeper contract provides an additional security layer to the upgradeable contracts on the Colle platform. It allows the owner to specify permitted implementations to which upgradeable contracts can upgrade.

Key Features:

• Securing Upgradeable Contracts: Upgradeable contracts introduce a new potential attack vector to the platform. The UpgradeGatekeeper contract helps mitigate this risk by limiting the possible upgrades to a set of approved implementations.

• Owner-Controlled Implementation Approval: The owner of the UpgradeGatekeeper contract has the authority to define which implementations are safe for upgradeable contracts to upgrade to. This puts a reliable authority in charge of securing the upgrade process.

• Future DAO Control: On launch, the owner of the UpgradeGatekeeper will be a multisig account controlled by Colle. As the platform evolves, Colle plans to establish a Decentralized Autonomous Organization (DAO). The ownership of the UpgradeGatekeeper will be transferred to this DAO, ensuring that only upgrades approved by the community can be implemented.

The UpgradeGatekeeper contract provides crucial protection to the platform, mitigating potential risks associated with contract upgrades, and ensuring that the integrity and security of the Colle marketplace remain uncompromised.