Functional Requirements
This document outlines the functional requirements of the Colle platform's smart contracts. These requirements have been meticulously defined to help auditors, developers, and stakeholders understand the intended functionality of the platform.
1. Submodule Registration
Colle possesses the authority to register and unregister various submodules to the marketplace, enhancing functionality, expanding the types of tradable assets, and managing user access and permissions.
ColleCollections: Colle can register ColleCollections to the marketplace. These are specific NFT collections that are allowed to be traded on the platform.
Currencies: Colle can register Currency contracts. These are contracts that contain a reference to a specific ERC20 currency and a helper method. The helper method is designed to convert the ERC20 currency value to a USDC value. This conversion is used for royalty calculations and minimum price checks. Currency, USDC is initially the only supported currency of the platform.
KYC'd Accounts: Colle can register KYC'd accounts, granting them the permissions necessary to interact with the marketplace. This ensures compliance with legal regulations and enhances platform security.
Markets: Colle can register market contracts. These markets are able to gate sale creation. Currently, Listing and Offer markets are the two types that exist, but this can be extended in the future.
Royalty Tiers: Colle can register royalty tiers. These tiers are assigned to accounts to determine the commission rates and royalty rates they pay. This enables a dynamic commission system that can be adapted to suit different user types and market conditions.
2. Token Minting and Sale Metadata
Colle should be able to mint a token in ColleCollection contract on a users behalf.
Colle or users should be able to update the sale metadata for a token before a sale can occur.
3. KYC and Account Management
Sellers and Buyers must be KYC'd with Colle before any sale can occur. Colle can register accounts via the MarketHub (extending KYCRegistry) and assign them a tier.
Colle can halt or ban accounts in the KYC registry at Colle's discretion. This does not prevent existing sales from being completed but prevents new sales from being started for the affected party.
4. Listing Market Operations
Sellers should be able to list a token for sale via the ListingMarketUpgradeable contract in their preferred supported currency.
Sellers should be able to delist these listings.
Buyers should be able to buy a listed token.
5. Offer Market Operations
Buyers should be able to make an offer for a token via the OfferMarketUpgradeable contract.
Buyers should be able to revoke their offers.
Sellers should be able to accept an offer.
6. Pricing and Payment Mechanisms
Listings and Offers should not be able to be for a price below the minimum (since Colle is paying for shipping out of our commission, we must at least cover shipping costs).
The Offer and Listing markets should support a pay-later mechanism.
Colle can be the spender of a sale, only if Colle sends the transaction, to allow for off-chain payments that Colle fronts upon receiving funds. Otherwise, the buyer is always the spender.
7. Sale States and Transitions
Upon a sale being created via a market (e.g., Listing or Offer markets), the EscrowUpgradeable contract creates the sale struct and acts as a state machine. A sales state is either AwaitingSettlement or AwaitingERC20Deposit.
AwaitingSettlement is the starting sale state if the sale is occuring off-chain, Colle is fronting the royalties/comissions costs, and must await off-chain payments to settle.
AwaitingERC20Deposit is the starting sale state if the user is paying their own costs directly on-chain.
Users can transition from AwaitingSettlement to AwaitingERC20Deposit, and Colle can transition from AwaitingERC20Deposit to AwaitingSettlement
AwaitingSettlement or AwaitingERC20Deposit states must transition to PendingSale before a sale can continue.
Sellers, Buyers, and Colle can update the sale to the appropriate states
View the Sale State Explained section for a breakdown on how a sale gets created, state transitioned, and sale is finalized/cancelled.
8. Sale Resolution
If a sale is completed, the seller receives the funds, and the buyer receives the NFT.
If a sale is cancelled, the NFT is returned to the seller, and the funds returned to the buyer.
If there is an issue with the product, the NFT is returned to the seller, and the funds returned to the buyer.
If there is an issue with delivery, the NFT and funds are sent to Colle for manual resolution, who will work with the insurance to make all parties whole.
9. Commission, Royalties and Taxes
Once a sale is completed, royalties commission and taxes will be paid out. The royalty and commission fees are determined by the seller's tier in the KYC module, and taxes determined at purchase time by Colle.
Commission is paid out to Colle's address.
Royalties are paid out to the initial order and to previous owners in the
Taxes are paid out to a separate Colle address. Taxes are only collected for domestic sales. If taxes are set to zero, its because either they do not apply, or are being handled off-chain by Stripe, ParcelPro, and/or Avalara.
View the Royalty Pool Explained section for a breakdown on how royalties are distributed.
10. EIP-712 Permits
Every action above that is invoked by a user, whether buyer or seller, can be done either through a traditional transaction, or a EIP-712 signature that is relayed by Colle.
Last updated