Solidity API

TokenExchange

Trade contract to enable the exchange of ERC-20 tokens with other ERC-20 tokens or through off-chain settlements.

Extends the AbstractTokenExchange contract, incorporating advanced mechanisms for whitelisting exchange callers, enhancing the base functionality with added security and flexibility.

exchangeCallers

mapping(address => bool) exchangeCallers

Mapping of addresses with authority to perform exchange operations.

Stores a boolean value indicating whether an address is authorized as an exchange caller.

attachments

mapping(string => address) attachments

Maps CID strings to the address that submitted them

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

ExchangeCallers

event ExchangeCallers(address depositor, address[] exchangeCallers)

Logs the address of the depositor and the list of exchange callers.

Triggered when exchange callers are set or updated for a depositor.

ExchangeInfoSet

event ExchangeInfoSet(enum AbstractTokenExchange.ExchangeType exchangeType, uint256 ratio, address baseToken, address quoteToken)

Logs the type of exchange, the exchange ratio, and the addresses of the base token and quote token.

Triggered when exchange information is configured for the contract.

AttachmentAdded

event AttachmentAdded(string cid, address submitter)

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

Triggered when a new attachment is added to the contract.

TokenExchangeUnauthorizedExchangeCaller

error TokenExchangeUnauthorizedExchangeCaller(address sender)

Logs the address of the unauthorized caller.

Thrown when an unauthorized caller attempts to perform the operation.

TokenExchangeAttachmentAlreadyAdded

error TokenExchangeAttachmentAlreadyAdded(string cid)

Logs the Content Identifier (CID) of the duplicate attachment.

Thrown when an attempt is made to add an attachment that already exists.

TokenExchangeExchangeInfoAlreadyAdded

error TokenExchangeExchangeInfoAlreadyAdded()

This error does not log additional information but indicates the configuration conflict.

Thrown when an attempt is made to set exchange information that is already configured.

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 _depositor, string _erc1155Uri) public

Constructor to initialize the depositor address and the ERC-1155 URI.

Calls the AbstractTokenExchange constructor with the provided URI and sets the depositor address.

Parameters

Name	Type	Description
_depositor	address	The address of the depositor to be set.
_erc1155Uri	string	The URI for the ERC-1155 token metadata.

setExchangeInfo

function setExchangeInfo(enum AbstractTokenExchange.ExchangeType _exchangeType, uint256 _ratio, address _baseToken, address _quoteToken, address[] _disputeResolvers, uint256 _exchangeWindow, uint256 _refutationWindow) external

Set the exchange information for the contract.

_This function allows the depositor to set up parameters for either token-for-token or fiat-for-token exchanges. The exchange type dictates the additional parameters required, such as tokens or dispute resolvers.

Requirements:

• The function can only be called by the depositor.
• Exchange information must not have been previously set.
• Tokens used in the exchange must be valid and ERC-20 compatible._

Parameters

Name	Type	Description
_exchangeType	enum AbstractTokenExchange.ExchangeType	The type of exchange: 0 for token-for-token, 1 for fiat-for-token.
_ratio	uint256	The exchange ratio (scaled to 10^18). Required only for token-for-token exchange.
_baseToken	address	The address of the token to be exchanged to.
_quoteToken	address	The address of the token to be used in the exchange. Required only for token-for-token exchange.
_disputeResolvers	address[]	Addresses for account with authority to resolve refutations. Required only for fiat-for-token exchange.
_exchangeWindow	uint256	The Epoch time in seconds before which an exchange/exchangeCommence can be performed.
_refutationWindow	uint256	The Time in seconds from each exchangeCommence request when a depositor may refute the exchange. Required only for fiat-for-token exchange. Error: - TokenExchangeExchangeInfoAlreadyAdded: Reverted if attempt to set exchange information that is already configured is made. - TokenExchangeInvalidToken: Reverted when an invalid token is provided for exchange. Emits: - ExchangeInfoSet: Emitted once exchange info is set successfully.

deposit

function deposit(uint256 _value) external

Allows the depositor to deposit ERC-20 baseTokens and receive equivalent ERC-1155 tokens.

_The depositor can call this function to transfer ERC-20 baseTokens to the contract, which will then mint equivalent ERC-1155 tokens to the depositor's address.

Requirements:

• The function can only be called by the depositor.
• The contract must not be paused (nonReentrant modifier)._

Parameters

Name	Type	Description
_value	uint256	The amount of baseTokens to deposit. Emits: - TokensDeposited: Emitted after successful deposit and minting of ERC-1155 tokens.

withdraw

function withdraw(uint256 _value, address _to) external

Allows the depositor to withdraw baseTokens that are not undergoing an exchange.

_This function allows the depositor to withdraw ERC-20 baseTokens from the contract, provided that the exchange window has passed and the requested amount does not exceed the available balance (excluding tokens undergoing exchange).

Requirements:

• The exchange window must be closed.
• The depositor must have sufficient balance to cover the withdrawal._

Parameters

Name	Type	Description
_value	uint256	The amount of baseTokens to withdraw.
_to	address	The address that will receive the withdrawn ERC-20 tokens. Errors: - TokenExchangeActiveExchangeWindow: Reverted if the withdrawal request is made before the exchange window has closed. - TokenExchangeInsufficientBalance: Reverted if the requested withdrawal exceeds the available balance. Emits: - TokensWithdrawn: Emitted once the withdrawal is successful.

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 depositor
• CID must not already exist_

Parameters

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

whitelistExchangeCallers

function whitelistExchangeCallers(address[] _exchangeCallers) external

Whitelists a list of exchange callers, allowing them to perform exchange-related operations.

_This function allows the depositor to whitelist multiple addresses as exchange callers. The addresses added to the whitelist will be able to perform operations related to the exchange.

Requirements:

• The caller must be the depositor._

Parameters

Name	Type	Description
_exchangeCallers	address[]	An array of addresses to be whitelisted as exchange callers. Emits: - ExchangeCallers: Emitted upon successful addition of exchange callers.

exchange

function exchange(uint256 _quoteValue) external

Allows users to perform token-for-token exchanges.

_This function allows whitelisted callers to exchange ERC-20 quoteTokens for the corresponding baseToken.

Requirements:

• The caller must be whitelisted as an exchange caller (checked via exchangeCallers mapping)._

Parameters

Name	Type	Description
_quoteValue	uint256	The amount of ERC-20 quoteTokens to exchange. Error: - TokenExchangeUnauthorizedExchangeCaller: Reverted if the caller is not whitelisted to perform the exchange. Emits: - Exchange: Emitted upon successful completion of the token-for-token exchange.

initiateExchange

function initiateExchange(uint256 _baseValue) external

Commences a fiat-for-token exchange and stores the exchange request.

_This function allows whitelisted callers to initiate a fiat-for-token exchange. It generates a unique request ID based on the caller's address, the current block timestamp, and the amount of tokens requested.

Requirements:

• The caller must be whitelisted as an exchange caller._

Parameters

Name	Type	Description
_baseValue	uint256	The amount of tokens requested in the exchange. Error: - TokenExchangeUnauthorizedExchangeCaller: Reverted if an unauthorized caller attempts to perform the operation. Emits: - ExchangeCommenced: Emitted after the exchange has been successfully initiated and the request has been stored.

refuteExchange

function refuteExchange(uint256 _exchangeRequestId) external

Allows the depositor to refute a fiat-for-token exchange request.

_This function enables the depositor to refute a fiat-for-token exchange request using its unique identifier.

Requirements:

• The caller must be the depositor (enforced by the onlyDepositor modifier)._

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The unique identifier for the exchange request that is being refuted. Emits: - ExchangeRefuted: Emitted after the exchange request has been successfully refuted.

nullifyRefutation

function nullifyRefutation(uint256 _exchangeRequestId) external

Nullify a refutation, marking the exchange request as unRefuted.

_This function allows the depositor or a disputeResolver to nullify a previously made refutation on an exchange request.

Requirements:

• The caller must be the depositor or a disputeResolver.
• The exchange request must exist and must have been refuted._

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request whose refutation is to be nullified. Error: - TokenExchangeUnauthorizedResolver Reverted if an unauthorized resolver attempts to resolve an exchange. Emits: - RefutationNullified: Emitted after the refutation is successfully nullified.

nullifyExchange

function nullifyExchange(uint256 _exchangeRequestId) external

Nullifies a refuted exchange request, removing it and unlocking the depositor's tokens.

_This function allows a disputeResolver to nullify a refuted exchange request. It removes the refutation and unlocks any tokens that were previously locked due to the refutation.

Requirements:

• The caller must be a registered dispute resolver (enforced by the TokenExchangeUnauthorizedResolver check).
• The exchange request must exist and have been refuted._

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request to nullify. Error: - TokenExchangeUnauthorizedResolver Reverted if an unauthorized resolver attempts to resolve an exchange. Emits: - ExchangeNullified: Emitted after the exchange request is successfully nullified.

completeExchange

function completeExchange(uint256 _exchangeRequestId) external

Completes a fiat-for-token exchange once the refutation window has passed and no active refutations are present.

_This function allows the exchange process to be completed after the refutation window has expired, ensuring that no active refutations are present. Once the exchange is completed, the requested tokens are transferred to the appropriate parties.

Requirements:

• The refutation window must have passed.
• No active refutations should be present for the exchange request._

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request to complete. Emits: - ExchangeCompleted: Emitted after the successful completion of the exchange request.

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes data) public

Transfers ERC-1155 tokens from one address to another.

_This function overrides the {IERC1155-safeTransferFrom} implementation to include additional checks.

Requirements:

• The caller must be the from address or have been approved via isApprovedForAll._

Parameters

Name	Type	Description
from	address	The address of the current token holder.
to	address	The address receiving the tokens.
id	uint256	The ID of the ERC-1155 token being transferred.
value	uint256	The amount of tokens to transfer.
data	bytes	Additional data sent along with the call. Error: - ERC1155MissingApprovalForAll: Reverted if the caller is not the from address and lacks the necessary approval.

safeBatchTransferFrom

function safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] values, bytes data) public

Transfers multiple ERC-1155 token types from one address to another in a single transaction.

_This function overrides the {IERC1155-safeBatchTransferFrom} implementation to include additional ownership and approval checks.

Requirements:

• The caller must be the from address or have been approved via isApprovedForAll.
• ids and values arrays must have the same length._

Parameters

Name	Type	Description
from	address	The address of the current token holder.
to	address	The address receiving the tokens.
ids	uint256[]	An array of token IDs being transferred.
values	uint256[]	An array of amounts for each token ID being transferred.
data	bytes	Additional data sent along with the call. Error: - ERC1155MissingApprovalForAll: Reverted if the caller is not the from address and lacks the necessary approval.