Solidity API

AbstractTokenExchange

Template for trade contracts that leverage exchange of erc-20 tokens with other erc-20 tokens or erc-20 tokens with off-chain settlement.

This contract provides the base for exchanges, refutations, and balances management for such processes. This contract expects to be implemented by further fine-tuned trade contracts and remains abstract itself.

ExchangeType

The type of exchange to be executed via the contract.

This governs the exchange info requirements and the subsequent exchange process to be followed - 0: TOKEN_FOR_TOKEN - 1: FIAT_FOR_TOKEN

enum ExchangeType {
  TOKEN_FOR_TOKEN,
  FIAT_FOR_TOKEN
}

ExchangeRequest

Represents a request for exchange with details about the sender, value, timestamp, and refutation status.

This struct is used to manage exchange requests in the contract.

struct ExchangeRequest {
  address sender;
  uint256 value;
  uint256 timestamp;
  bool refuted;
}

DepositorSet

event DepositorSet(address depositor)

This allows tracking of who is authorized to deposit and manage exchanges.

Triggered when the depositor address is set.

TokensDeposited

event TokensDeposited(address depositor, address token, uint256 value, uint256 tokenId)

Logs the address of the depositor, the token being deposited, the value of tokens, and the token ID.

Triggered when tokens are deposited by the depositor.

TokensWithdrawn

event TokensWithdrawn(address from, address token, uint256 value, address to)

Logs the sender address, the token being withdrawn, the amount, and the recipient address.

Triggered when tokens are withdrawn from the contract.

TokensExchanged

event TokensExchanged(address caller, address quoteToken, uint256 quoteValue, address baseToken, uint256 baseValue)

Logs the caller who initiated the exchange, the quote token being exchanged, the quote value, the base token being received, and the value of the base token.

Triggered when a token exchange occurs.

ExchangeCommenced

event ExchangeCommenced(uint256 exchangeRequestId, address requester, address baseToken, uint256 value)

Logs the exchange request ID, the requester’s address, the base token being exchanged, and the value being exchanged.

Triggered when an exchange is commenced.

ExchangeCompleted

event ExchangeCompleted(uint256 exchangeRequestId, address requester, address baseToken, uint256 value)

Logs the exchange request ID, the requester’s address, the base token, and the completed exchange value.

Triggered when an exchange is completed.

ExchangeRefuted

event ExchangeRefuted(address depositor, uint256 exchangeRequestId)

Logs the depositor's address who refuted the exchange and the exchange request ID.

Triggered when an exchange is refuted.

RefutationNullified

event RefutationNullified(address sender, uint256 exchangeRequestId)

Logs the address of the sender who nullified the refutation and the corresponding exchange request ID.

Triggered when a refutation is nullified.

ExchangeNullified

event ExchangeNullified(address sender, uint256 exchangeRequestId)

Logs the address of the sender who nullified the exchange and the corresponding exchange request ID.

Triggered when an exchange is nullified (canceled or invalidated).

TokenExchangeInvalidToken

error TokenExchangeInvalidToken(address tokenAddress, string msg)

Logs the token address and a message describing the reason for invalidity.

Thrown when an invalid token is provided for exchange.

TokenExchangeInvalidExchangeWindow

error TokenExchangeInvalidExchangeWindow(uint256 exchangeWindow, uint256 requestTimestamp)

TokenExchangeActiveExchangeWindow

error TokenExchangeActiveExchangeWindow(uint256 exchangeWindowTill, uint256 requestTimestamp)

It provides the timestamp until which the exchange window is active and the timestamp of the request.

Thrown when a withdraw request is attempted before the exchange window has closed.

TokenExchangeInactiveExchangeWindow

error TokenExchangeInactiveExchangeWindow(uint256 exchangeWindowTill, uint256 requestTimestamp)

It provides the timestamp until which the exchange window is open and the timestamp of the request.

Thrown when an exchange request is attempted after the exchange window has closed.

TokenExchangeInsufficientBalance

error TokenExchangeInsufficientBalance(uint256 balance, uint256 requested)

Logs the current balance and the requested amount.

Thrown when an exchange request exceeds the available balance.

TokenExchangeInsufficientAllowance

error TokenExchangeInsufficientAllowance(uint256 allowance, uint256 required)

It provides the current allowance and the required allowance to perform the action.

Thrown when there is not enough allowance to execute a token exchange.

TokenExchangeUnauthorizedDepositor

error TokenExchangeUnauthorizedDepositor(address sender, address depositor)

Logs the address of the sender and the authorized depositor address.

Thrown when a sender that is not authorized tries to perform a deposit-related action.

TokenExchangeInvalidExchangeRequest

error TokenExchangeInvalidExchangeRequest(uint256 requestId)

Logs the invalid request ID.

Thrown when an exchange request is invalid, often used to prevent request collisions.

TokenExchangeInactiveRefutationWindow

error TokenExchangeInactiveRefutationWindow(uint256 refutationWindowTill, uint256 refuteTimestamp)

It provides the timestamp until which refutation is allowed and the timestamp of the refute attempt.

Thrown when an attempt to refute an exchange happens after the refutation window has expired.

TokenExchangeActiveRefutationWindow

error TokenExchangeActiveRefutationWindow(uint256 refutationWindowTill, uint256 requestTimestamp)

It provides the timestamp until which refutation is allowed and the timestamp of the request.

Thrown when an attempt to exchange happens while the refutation window is still open.

TokenExchangeInvalidRefutationWindow

error TokenExchangeInvalidRefutationWindow(uint256 refutationWindowTill, uint256 requestTimestamp)

It provides the timestamp until which refutation is allowed and the timestamp of the request.

Thrown when the refutation window is invalid, often caused by mismatched timestamps.

TokenExchangeUnauthorizedResolver

error TokenExchangeUnauthorizedResolver(address sender)

Logs the address of the sender attempting the resolution.

Thrown when someone who is not authorized attempts to resolve an exchange.

TokenExchangeUnauthorizedRequester

error TokenExchangeUnauthorizedRequester(address sender, address originalRequester)

Logs the sender's address and the original requester's address.

Thrown when someone other than the original requester attempts to make a request.

TokenExchangeInvalidRefutationStatus

error TokenExchangeInvalidRefutationStatus(uint256 exchangeRequestId)

It provides the exchange request ID that has the invalid refutation status.

Thrown when an exchange request has an invalid refutation status.

TokenExchangeTransferFailed

error TokenExchangeTransferFailed(address from, address to, uint256 amount)

Indicates that an ERC-20 token transfer operation has failed.

This error is thrown when the transfer of tokens between addresses does not succeed.

Parameters

Name	Type	Description
from	address	The address from which the tokens were attempted to be transferred.
to	address	The address to which the tokens were intended to be transferred.
amount	uint256	The amount of tokens that failed to transfer.

onlyDepositor

modifier onlyDepositor()

Restricts access to only the authorized depositor.

_This modifier ensures that only the designated depositor can execute the function it is applied to.

Error:

• TokenExchangeUnauthorizedDepositor: Reverted if the caller is not the authorized depositor._

constructor

constructor(string _erc1155uri) internal

Initializes the contract with the given ERC-1155 URI.

This constructor sets the initial URI for the ERC-1155 token and inherits functionality from the ERC1155 contract.

Parameters

Name	Type	Description
_erc1155uri	string	The URI to be set for the ERC-1155 token.

_setDepositor

function _setDepositor(address _depositor) internal

Sets the depositor's address.

Sets the address of the depositor for the contract.

Parameters

Name	Type	Description
_depositor	address	The new address to be assigned as the depositor. Emits: - DepositorSet: Emitted when the depositor is successfully set.

getDepositor

function getDepositor() public view virtual returns (address)

Retrieves the address of the depositor for the contract.

This function allows external callers to view the current depositor address.

Return Values

Name	Type	Description
[0]	address	The address of the depositor stored in the contract.

getExchangeType

function getExchangeType() public view virtual returns (enum AbstractTokenExchange.ExchangeType)

Retrieves the current exchange type.

This function returns the type of exchange (either 0n for TOKEN_FOR_TOKEN or 1n for FIAT_FOR_TOKEN) for the contract.

Return Values

Name	Type	Description
[0]	enum AbstractTokenExchange.ExchangeType	The type of exchange set for this contract.

_setExchangeType

function _setExchangeType(enum AbstractTokenExchange.ExchangeType _exchangeType) internal

This function may include validation logic for the exchange type in the future.

Sets the exchange type internally.

Parameters

Name	Type	Description
_exchangeType	enum AbstractTokenExchange.ExchangeType	The new exchange type to be set.

getRatio

function getRatio() public view virtual returns (uint256)

Retrieves the exchange ratio.

This function returns the current exchange ratio used for the transaction.

Return Values

Name	Type	Description
[0]	uint256	The current exchange ratio.

_setRatio

function _setRatio(uint256 _newRatio) internal

Sets the exchange ratio used for token exchanges.

This internal function sets a new exchange ratio for the contract. The ratio determines the rate at which quote tokens are exchanged for base tokens.

Parameters

Name	Type	Description
_newRatio	uint256	The new exchange ratio to be applied.

getBaseToken

function getBaseToken() public view virtual returns (address)

Retrieves the base token address.

This function returns the address of the base token used in the exchange process.

Return Values

Name	Type	Description
[0]	address	The address of the base token used in the exchange.

getQuoteToken

function getQuoteToken() public view virtual returns (address)

Retrieves the quote token address.

This function returns the address of the quote token used in the exchange process.

Return Values

Name	Type	Description
[0]	address	The address of the quote token used in the exchange.

getExchangeWindow

function getExchangeWindow() public view virtual returns (uint256)

Retrieves the current exchange window timestamp.

This function returns the timestamp that represents the current exchange window.

Return Values

Name	Type	Description
[0]	uint256	The timestamp representing the exchange window.

_setExchangeWindow

function _setExchangeWindow(uint256 _newExchangeWindow) internal

Ensures that the new exchange window is a future timestamp and sets the exchangeWindow.

This function validates the provided timestamp to ensure it's in the future and sets it as the new exchange window.

Parameters

Name	Type	Description
_newExchangeWindow	uint256	The new exchange window timestamp to be set. Error: - TokenExchangeInvalidRefutationWindow: If the provided timestamp is not in the future.

isDisputeResolver

function isDisputeResolver(address resolver) public view virtual returns (bool)

Determines whether a given address is registered as a dispute resolver.

This public view function checks the contract's record of dispute resolvers to confirm if the specified address has been assigned dispute resolution permissions.

Parameters

Name	Type	Description
resolver	address	The address to verify for dispute resolver registration.

Return Values

Name	Type	Description
[0]	bool	True if the address is a registered dispute resolver, false otherwise.

_setDisputeResolver

function _setDisputeResolver(address _resolver, bool _allow) internal

Updates the permissions of a dispute resolver.

This function grants or revokes the dispute resolver permissions for the given address.

Parameters

Name	Type	Description
_resolver	address	The address of the dispute resolver.
_allow	bool	Whether to grant (true) or revoke (false) resolver permissions.

getExchangeRequest

function getExchangeRequest(uint256 requestId) public view virtual returns (struct AbstractTokenExchange.ExchangeRequest exchangeRequest)

Retrieves details of a specific exchange request.

This function returns the details of an exchange request identified by the given request ID.

Parameters

Name	Type	Description
requestId	uint256	The unique identifier of the exchange request.

getRefutationWindow

function getRefutationWindow() public view virtual returns (uint256)

Retrieves the current refutation window duration.

This function returns the duration of the refutation window, which is the period allowed for disputing exchanges.

Return Values

Name	Type	Description
[0]	uint256	The duration of the refutation window.

_setRefutationWindow

function _setRefutationWindow(uint256 _newRefutationWindow) internal

Sets the refutation window internally.

This function updates the duration of the refutation window.

Parameters

Name	Type	Description
_newRefutationWindow	uint256	The new duration for the refutation window.

_setBaseToken

function _setBaseToken(address _baseToken) internal

Sets the base token address internally.

This function set the base token address used in the exchange.

Parameters

Name	Type	Description
_baseToken	address	The address of the base token to set.

_setQuoteToken

function _setQuoteToken(address _quoteToken) internal

Sets the quote token address internally.

This function sets the quote token address used in the exchange.

Parameters

Name	Type	Description
_quoteToken	address	The address of the quote token to set.

getDepositUnderExchange

function getDepositUnderExchange() public view virtual returns (uint256)

Retrieves the deposit amount currently under exchange.

This function returns the amount of the deposit that is currently under exchange.

Return Values

Name	Type	Description
[0]	uint256	The amount of the deposit under exchange.

_deposit

function _deposit(address _to, address _token, uint256 _value) internal

Deposit ERC-20 baseTokens to an address into the contract and mint corresponding ERC-1155 tokens.

Caller must have approved the contract to spend value amount of the ERC-20 token provided.

Parameters

Name	Type	Description
_to	address
_token	address
_value	uint256	The amount of tokens to deposit. Error - TokenExchangeTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - TokensDeposited: Emitted upon successful deposit of tokens.

_withdraw

function _withdraw(address _from, address _to, address _token, uint256 _value) internal

Withdraw deposited ERC-20 tokens from the contract.

The caller must own equivalent ERC-1155 tokens for the same ERC-20 contract being withdrawn.

Parameters

Name	Type	Description
_from	address	Address of the account on erc-1155 balances to withdraw from.
_to	address	The address to credit the withdrawn ERC-20 tokens.
_token	address	The address ERC-20 to be withdrawn from ERC-1155 deposited balances.
_value	uint256	The amount of tokens to withdraw. Error - TokenExchangeTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - TokensWithdrawn: Emitted upon successful withdrawn of tokens.

_exchange

function _exchange(uint256 _quoteValue) internal

Single-step exchange for token-for-token exchange.

The caller must approve the contract for sufficient quoteToken ERC-20 tokens, and the contract will exchange quoteToken for baseToken based on the established ratio. This function can only be called during the exchangeWindow.

Parameters

Name	Type	Description
_quoteValue	uint256	The value of ERC-20 quoteToken to be exchanged. Error - TokenExchangeInactiveExchangeWindow: Reverted if exchange is not called within the exchange window. - TokenExchangeInsufficientAllowance: Reverted if there is not enough allowance to execute a token exchange. - TokenExchangeTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - TokensExchanged: Emitted upon successful exchange.

_initiateExchange

function _initiateExchange(uint256 _baseValue, address _exchangeCaller, uint256 _exchangeRequestId) internal

Commences a refutable fiat-for-token exchange process.

This function allows users to initiate an exchange request during the exchange window. The request will be recorded and can be refuted by the depositor within the refutation window.

Parameters

Name	Type	Description
_baseValue	uint256	The value of ERC-20 baseToken to be exchanged.
_exchangeCaller	address	The address initiating the exchange request.
_exchangeRequestId	uint256	A unique identifier for the exchange request. Error: - TokenExchangeInactiveExchangeWindow: Reverted if exchange is not called within the exchange window. - TokenExchangeInsufficientBalance: Reverted if the exchange request exceeds the available balance. - TokenExchangeInvalidExchangeRequest: Reverted if exchange request is invalid. Emits: - ExchangeCommenced: Emitted upon successful initiation of exchange.

_refuteExchange

function _refuteExchange(uint256 _exchangeRequestId) internal

Refute an exchange request by the depositor.

The caller must be the depositor and the exchange request should be available and within the refutable time frame.

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request to be refuted. Error: - TokenExchangeInvalidExchangeRequest: Reverted if exchange request is invalid. - TokenExchangeInactiveRefutationWindow: Reverted if refuting the exchange happens after refutation window has expired. Emits: - ExchangeRefuted: Emitted upon successful refutation of exchange.

_nullifyRefutation

function _nullifyRefutation(uint256 _exchangeRequestId) internal

Nullify a refutation, marking the exchange request as unRefuted.

Can only be called by the depositor or a disputeResolver. The exchange request must exist and have been refuted.

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request to nullify refutation. Error: - TokenExchangeInvalidExchangeRequest: Reverted if exchange request is invalid. - TokenExchangeInvalidRefutationStatus: Reverted if exchange request has an invalid refutation status. Emits: - RefutationNullified: Emitted upon successful nullify of the refutation.

_nullifyExchange

function _nullifyExchange(uint256 _exchangeRequestId) internal

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

Can only be called by a dispute resolver. The exchange request must exist and be refuted.

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The ID of the exchange request to nullify. Error: - TokenExchangeInvalidExchangeRequest: Reverted if exchange request is invalid. - TokenExchangeInvalidRefutationStatus: Reverted if exchange request has an invalid refutation status. Emits: - ExchangeNullified: Emitted upon successful nullify of the exchange.

_completeExchange

function _completeExchange(uint256 _exchangeRequestId) internal

Completes a fiat-for-token exchange request after the refutation window has elapsed.

_Completes an exchange request by transferring tokens to the original request sender. Ensures the refutation window has elapsed, and the request is not refuted.

Requirements:

• The caller must be the original exchange request sender.
• The refutation window must have elapsed.
• The exchange request must not be refuted.
• The baseToken must have sufficient balance and approval for transfer._

Parameters

Name	Type	Description
_exchangeRequestId	uint256	The unique ID of the exchange request to be completed. Error: - TokenExchangeInvalidExchangeRequest: Reverted if exchange request is invalid. - TokenExchangeUnauthorizedRequester: Reverted if the caller is not the the original requester. - TokenExchangeActiveRefutationWindow: Reverted if the attempt to exchange happens while refutation window is still open. - TokenExchangeInvalidRefutationStatus: Reverted if exchange request has an invalid refutation status. - TokenExchangeTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - ExchangeCompleted: Emitted upon successful completion of the exchange.

_isCompatibleERC20

function _isCompatibleERC20(address token) internal view returns (bool, string)

Verifies if the given address is a valid ERC20 token by checking the presence of the transfer, transferFrom, and allowance functions using staticcall.

Parameters

Name	Type	Description
token	address	The token address to verify.

Return Values

Name	Type	Description
[0]	bool	_isCompatibleERC20 True if the address is a valid ERC20 token (with the required functions).
[1]	string