Solidity API

TradeToken

This contract extends OpenZeppelin's ERC20 implementation, providing additional functionality such as wrapping and unwrapping capabilities, wrap ratios, and secure transfer handling. It includes enhanced security features like reentrancy protection and ownership controls.

_Implements an advanced and customizable ERC20 token with wrapping and unwrapping capabilities, wrap ratios and secure transfer handling.

The contract supports two types of tokens:

• Mintable: New tokens can be created by the owner
• Wrappable: Tokens that can be wrapped into other TradeToken

Security features:

• Reentrancy protection on all state-modifying functions
• Ownership controls for sensitive operations
• Transfer acceptance checks for contract recipients
• Twin contract verification for wrapping operations_

TradeTokenType

Defines the type of TradeToken.

This enum is used to categorize the types of trade tokens available, each with different properties and behaviors related to token creation and wrapping.

enum TradeTokenType {
  Mintable,
  Wrappable
}

tradeTokenType

enum TradeToken.TradeTokenType tradeTokenType

The type of this TradeToken instance

The type of TradeToken instance, defined by the TradeTokenType enum. This variable helps identify whether the token is Mintable or Wrappable.

attachments

mapping(string => address) attachments

Mapping to track IPFS Content Identifiers (CIDs) and their submitters.

Mapping to store attachments and the sender attaching them(cid => sender address)

AttachmentAdded

event AttachmentAdded(string cid, address submitter)

Logs the IPFS Content Identifier (CID) and the address of the submitter.

Triggered when a new attachment is added to the contract.

WrapRatioAdded

event WrapRatioAdded(address childTradeTokenAddress, uint256 ratio)

Logs the address of the child Trade Token and the wrap ratio.

Triggered when a new wrap ratio is added for a child Trade Token.

WrapRatioReceived

event WrapRatioReceived(address tradeTokenAddress, uint256 ratio)

Logs the address of the Trade Token setting the ratio and the received wrap ratio.

Triggered when a wrap ratio is received from another Trade Token.

TradeTokenMintingNotAllowed

error TradeTokenMintingNotAllowed()

Logs when minting is attempted but not allowed.

Thrown when minting is not allowed for the Trade Token.

TradeTokenUnauthorizedTradeTokenOwner

error TradeTokenUnauthorizedTradeTokenOwner()

Logs when an unauthorized owner attempts to perform an action.

Thrown when an unauthorized Trade Token owner tries to perform an action.

TradeTokenInvalidTwinContract

error TradeTokenInvalidTwinContract(address target)

Logs when an invalid twin contract address is provided.

Thrown when an address is not a valid twin contract.

TradeTokenWrapRatioNotRegistered

error TradeTokenWrapRatioNotRegistered(address target)

Logs when a wrap ratio is not registered for a given Trade Token.

Thrown when a wrap ratio has not been registered for the specified Trade Token.

TradeTokenWrapRatioAlreadyExists

error TradeTokenWrapRatioAlreadyExists(address target)

Logs when a wrap ratio already exists for a given Trade Token.

Thrown when a wrap ratio already exists for the specified Trade Token.

TradeTokenInsufficientBalanceForWrap

error TradeTokenInsufficientBalanceForWrap(uint256 available, uint256 required)

Logs when the caller does not have sufficient balance to wrap tokens.

Thrown when the caller does not have enough balance to wrap tokens.

TradeTokenTransferFailed

error TradeTokenTransferFailed(address to, uint256 value)

Logs when a token transfer fails.

Thrown when a token transfer fails.

TradeTokenAttachmentAlreadyAdded

error TradeTokenAttachmentAlreadyAdded(string cid)

Logs when an attachment with the same CID is already added.

Thrown when an attachment has already been added for the specified CID.

TradeTokenNonZeroInitialSupplyForWrappable

error TradeTokenNonZeroInitialSupplyForWrappable()

Logs when a wrappable Trade Token is created with a non-zero initial supply.

Thrown when the initial supply for a wrappable Trade Token is non-zero.

InvalidCid

error InvalidCid(string cid)

Indicates that the supplied CID does not conform to the expected format.

Thrown when an invalid/empty CID (Content Identifier) is provided.

constructor

constructor(address _initialOwner, string _tokenName, string _tokenSymbol, uint256 _initialSupply, enum TradeToken.TradeTokenType _tradeTokenType) public

Sets up the Trade Token with initial parameters.

The constructor ensures that: - If the token is Wrappable, the initial supply must be 0. - The token is minted to the initial owner's address upon deployment. - The token's name, symbol, and owner are set via the inherited ERC20 and Ownable contracts.

Parameters

Name	Type	Description
_initialOwner	address	Address of the initial owner of the token.
_tokenName	string	Name of the token.
_tokenSymbol	string	Symbol of the token.
_initialSupply	uint256	Initial supply of tokens to mint.
_tradeTokenType	enum TradeToken.TradeTokenType	Type of the Trade Token (either Mintable or Wrappable).

mint

function mint(address _account, uint256 _value) external

Creates new tokens and assigns them to the specified account.

This function allows the owner to mint new tokens, but only if the token type is Mintable.

Parameters

Name	Type	Description
_account	address	Address to receive the minted tokens.
_value	uint256	Amount of tokens to mint. Requirements: - The caller must be the contract owner. - The token must be of type Mintable. Emits: - Transfer: Emitted upon successful minting of new tokens.

burn

function burn(uint256 _value) external

Burns sender's owned tokens.

This function allows the sender to burn a specified amount of tokens from their own balance.

Parameters

Name	Type	Description
_value	uint256	Amount of tokens to be burnt. Requirements: - The caller must own at least the specified amount of tokens to burn. Emits: - Transfer event, as per the ERC20 specification, indicating the burned tokens.

wrap

function wrap(uint256 _value, address _wrapperTradeToken, address _to) external

Wraps tokens into another TradeToken at the predefined ratio.

_This function allows the user to wrap their tokens into another TradeToken at a predefined wrap ratio.

Requirements:

• The wrap ratio for the target TradeToken must be registered in the contract.
• The caller must have sufficient tokens to perform the wrap operation.

The function transfers tokens from the user's balance to the target wrapper token and then calls the target token's onReceiveWrappedTokens function to handle the wrapped token logic._

Parameters

Name	Type	Description
_value	uint256	Amount of tokens to wrap.
_wrapperTradeToken	address	Address of the target TradeToken to wrap into.
_to	address	Address to receive the wrapped tokens. Error: - TradeTokenWrapRatioNotRegistered: Reverted when a wrap ratio has not been registered for the specified Trade Token. - TradeTokenInsufficientBalanceForWrap: Reverted when the caller does not have enough balance to wrap tokens. Emits: - Transfer: Emitted upon successful transfer of tokens for wrapping.

unwrap

function unwrap(uint256 _value, address _wrappedTradeToken, address _to) external

Unwraps tokens back to their original form.

_This function allows the caller to unwrap wrapped tokens into their original form, based on the predefined wrap ratio. The unwrapping process involves burning the wrapped tokens and transferring the equivalent amount of the original tokens to the specified recipient.

Requirements:

• The caller must be the contract owner.
• A valid wrap ratio for the wrapped token must be registered._

Parameters

Name	Type	Description
_value	uint256	Amount of wrapped tokens to unwrap.
_wrappedTradeToken	address	Address of the TradeToken containing the original tokens.
_to	address	Address to receive the unwrapped tokens. Errors: - TradeTokenWrapRatioNotRegistered: Reverted if the wrap ratio for the target wrapped token is not registered. - TradeTokenTransferFailed: Reverted if the transfer of unwrapped tokens to the recipient fails. Emits: - Transfer: Emitted upon successful transfer unwrapped tokens to the recipient address. - Burn: Emitted upon successfully burning the wrapped tokens from the caller's balance.

onReceiveWrappedTokens

function onReceiveWrappedTokens(uint256 _value, address _to) external

Callback function for receiving wrapped tokens.

_This function is called by a wrapped token to mint new tokens in the contract that receives them. It is intended to be used as part of the wrapping mechanism to allow the transfer of wrapped tokens into the original form. The function verifies that the caller is a verified twin contract before proceeding with the minting process.

Requirements:

• The caller must be a verified twin contract._

Parameters

Name	Type	Description
_value	uint256	Amount of tokens to mint.
_to	address	Address to receive the minted tokens. Errors: - TradeTokenInvalidTwinContract: Reverted if the caller is not a valid twin contract. Emits: - Transfer event for minting the new tokens to the specified address.

setWrapRatio

function setWrapRatio(address _childTradeTokenAddress, uint256 _ratio) external

Sets the wrap ratio for a child TradeToken.

_This function allows the contract owner to define the wrap ratio for a specific child TradeToken. The wrap ratio determines the relationship between the original token and its wrapped counterpart (i.e., how much of the original token is equivalent to one unit of the wrapped token). The ratio is scaled by 10^18 to allow for precise fractional values.

Requirements:

• The child TradeToken must be a verified twin contract, ensuring the interaction is legitimate.
• The caller must be the owner of the child TradeToken, preventing unauthorized users from setting the wrap ratio.
• The wrap ratio must not already be set for the child TradeToken, ensuring no duplicate entries._

Parameters

Name	Type	Description
_childTradeTokenAddress	address	Address of the child TradeToken.
_ratio	uint256	Wrap ratio scaled by 10^18. Errors: - TradeTokenUnauthorizedTradeTokenOwner: Reverted if the caller is not the owner of the child TradeToken. - TradeTokenWrapRatioAlreadyExists: Reverted if a wrap ratio is already set for the child TradeToken. Emits: - WrapRatioAdded event when the wrap ratio is successfully set for the child TradeToken.

getWrapRatio

function getWrapRatio(address _tradeTokenAddress) external view returns (uint256)

Returns the wrap ratio for a given TradeToken address.

This function allows users to query the wrap ratio for a specific TradeToken.

Parameters

Name	Type	Description
_tradeTokenAddress	address	Address of the TradeToken to query.

Return Values

Name	Type	Description
[0]	uint256	The wrap ratio for the specified TradeToken address scaled by 10^18.

onReceiveWrapRatio

function onReceiveWrapRatio(uint256 _ratio) external

Callback function when receiving a wrap ratio from another TradeToken.

_This function is called by another TradeToken contract to notify the current contract about the wrap ratio between the tokens.

Requirements:

• Caller must be another TradeToken contract with the same deployed bytecode._

Parameters

Name	Type	Description
_ratio	uint256	The received wrap ratio. Emits: - WrapRatioReceived: Emitted upon successfully receiving and recording the wrap ratio.

transfer

function transfer(address _to, uint256 _value) public virtual returns (bool)

Overrides the ERC20 transfer function with additional security checks.

This function extends the standard ERC20 transfer method by adding security checks.

Parameters

Name	Type	Description
_to	address	Address to transfer tokens to.
_value	uint256	Amount of tokens to transfer.

Return Values

Name	Type	Description
[0]	bool	bool indicating success. Emits: - Transfer: Emitted upon successful transfer of tokens.

transferFrom

function transferFrom(address _from, address _to, uint256 _value) public virtual returns (bool)

Overrides the ERC20 transferFrom function with additional security checks.

This function extends the standard ERC20 transferFrom method by adding security checks

Parameters

Name	Type	Description
_from	address	Address to transfer tokens from.
_to	address	Address to transfer tokens to.
_value	uint256	Amount of tokens to transfer.

Return Values

Name	Type	Description
[0]	bool	bool indicating success. Emits: - Transfer: Emitted upon successful transfer of tokens.

addAttachment

function addAttachment(string _cid) external

Adds a new attachment to the contract.

_Adds a new attachment to the contract, associating a content identifier (CID) with the owner

Requirements:

• Only callable by owner
• CID must not already exist_

Parameters

Name	Type	Description
_cid	string	Content identifier for the attachment Error - TokenCustodyAttachmentAlreadyAdded: Reverted if there's an attempt to add an attachment that already exists. Emits: - AttachmentAdded: Emitted upon successful addition of attachment to the contract.

_verifyTwinContractBytecode

function _verifyTwinContractBytecode(address _target) internal view

Verifies that the target contract has identical bytecode as the current contract.

_This function compares the bytecode of the current contract with that of the target contract.

Requirements:

• The target contract must have the same bytecode as the current contract to pass the check._

Parameters

Name	Type	Description
_target	address	Address of the contract to verify. Error TradeTokenInvalidTwinContract: Reverted if the bytecode of the target contract does not match.