Solidity API

SalesOrder

Facilitates token sales in exchange for fiat or tokens.

Inherits from AbstractTokenExchange, Ownable, and ReentrancyGuard for enhanced functionality and security.

Status

Represents the possible statuses of a SalesOrder during its lifecycle.

Represents the overall status of the SalesOrder. - DRAFTING: The sale is awaiting configuration by the owner. - INITIATED: The sale has been configured.

enum Status {
  DRAFTING,
  INITIATED
}

OfferStatus

Defines the lifecycle statuses of an individual offer in the SalesOrder.

Represents the status of an individual offer. - NONE: No offer exists for the given ID. - ACTIVE: The offer is active and not accepted yet. - ACCEPTED: The offer has been accepted. - IN_PROGRESS: The sale process for the offer has started. - COMPLETED: The sale using this offer is completed. - CANCELLED: The offer and corresponding sale was cancelled.

enum OfferStatus {
  NONE,
  ACTIVE,
  ACCEPTED,
  IN_PROGRESS,
  COMPLETED,
  CANCELLED
}

Offer

Represents the details of an offer made by a potential buyer in the sales process.

Encapsulates the key information about an offer: - status: The current status of the offer, as defined by the OfferStatus enum. - offeror: The address of the user making the offer. - baseValue: The amount of base tokens the offer is made against. - quoteValue: The amount of quote tokens offered, applicable in token-for-token exchanges.

struct Offer {
  enum SalesOrder.OfferStatus status;
  address offeror;
  uint256 baseValue;
  uint256 quoteValue;
}

SELLER

address SELLER

Address of the seller depositing tokens for sale.

It initiates the sale process by depositing the tokens.

Offerors

mapping(address => bool) Offerors

Tracks authorized offeror addresses.

This mapping ensures that only approved offerors can offer.

status

enum SalesOrder.Status status

offers

mapping(uint256 => struct SalesOrder.Offer) offers

Mapping of offer IDs to their corresponding Offer data.

StatusUpdated

event StatusUpdated(enum SalesOrder.Status newStatus)

Logs the new status of the contract.

Triggered when the contract status is updated.

OfferMade

event OfferMade(uint256 offerId, address offeror, uint256 baseValue, uint256 quoteValue)

Logs the offer details, including the offer ID, the address of the offeror, the base value, and the quote value.

Triggered when a new offer is made.

OfferAccepted

event OfferAccepted(uint256 offerId)

Logs the ID of the accepted offer.

Triggered when an offer is accepted.

SaleInitiated

event SaleInitiated(uint256 offerId)

Logs the ID of the offer for which the sale was initiated.

Triggered when a sale is initiated for an offer.

SaleCompleted

event SaleCompleted(uint256 offerId)

Logs the ID of the offer for which the sale was completed.

Triggered when a sale is completed.

SaleRefuted

event SaleRefuted(uint256 offerId)

Logs the ID of the offer for which the sale was refuted.

Triggered when a sale is refuted.

SaleUnrefuted

event SaleUnrefuted(uint256 _offerId)

Logs the ID of the offer for which the sale was unrefuted.

Triggered when a sale is unrefuted.

SaleCancelled

event SaleCancelled(uint256 offerId)

Logs the ID of the cancelled offer.

Triggered when a sale is cancelled.

SalesOrderInvalidAddress

error SalesOrderInvalidAddress(address receivedAddress)

Logs the invalid address received.

Thrown when an invalid address is provided.

SalesOrderInvalidStatus

error SalesOrderInvalidStatus(enum SalesOrder.Status status)

Logs the invalid status of the sales order.

Thrown when the status of a sales order is invalid.

SalesOrderInvalidOfferId

error SalesOrderInvalidOfferId(uint256 conditionId)

Logs the invalid offer ID provided.

Thrown when an invalid offer ID is encountered in a sales order.

SalesOrderTransferFailed

error SalesOrderTransferFailed(address token, address to, uint256 amount)

Logs the address of the token, the recipient address, and the amount of tokens attempted to transfer.

Thrown when a token transfer fails.

SalesOrderUnauthorizedCaller

error SalesOrderUnauthorizedCaller(address sender)

Logs the address of the unauthorized caller.

Thrown when an unauthorized caller attempts the operation.

SalesOrderInvalidOfferStatus

error SalesOrderInvalidOfferStatus(uint256 offerId, enum SalesOrder.OfferStatus status)

Logs the offer ID and its invalid status.

Thrown when an offer has an invalid status.

constructor

constructor(address _initialOwner, address _seller, string _erc1155Uri) public

Initializes the contract with the owner, seller and ERC-1155 URI.

Parameters

Name	Type	Description
_initialOwner	address	The initial owner of the contract.
_seller	address	The address of the seller.
_erc1155Uri	string	The metadata URI for the ERC-1155 tokens.\ Error: - SalesOrderInvalidAddress: Reverted when an invalid address is provided.

initiate

function initiate(enum AbstractTokenExchange.ExchangeType _saleType, address _baseToken, address _quoteToken, address[] _offerorWhitelist, uint256 _activeTill, uint256 _refutationWindow, address _disputeResolver) external

Initiates the SalesOrder with the parameters of sales. @dev

• Can only be called by the owner.
• Must be in the DRAFTING stage.
• Configures the exchange type, base and quote tokens, active duration, refutation window, and dispute resolver.
• Whitelists offerors for making offers in the sales order.
• This function checks compatibility of _baseToken and _quoteToken with ERC-20 standards.
• For TOKEN_FOR_TOKEN sales, _quoteToken is validated and set.

Parameters

Name	Type	Description
_saleType	enum AbstractTokenExchange.ExchangeType	The type of exchange (TOKEN_FOR_TOKEN or FIAT_FOR_TOKEN).
_baseToken	address	The address of the ERC-20 token being sold (base token).
_quoteToken	address	The address of the ERC-20 token used as payment (quote token); required for TOKEN_FOR_TOKEN.
_offerorWhitelist	address[]	A list of addresses permitted to make offers.
_activeTill	uint256	The timestamp until which the SalesOrder remains active.
_refutationWindow	uint256	The duration (in seconds) allowed for refuting offers.
_disputeResolver	address	The address of the account or contract designated to resolve disputes. Error: - SalesOrderInvalidStatus: Reverted when the status of a sales order is invalid.. - SalesOrderInvalidAddress: Reverted when an invalid address is provided. Emits: - StatusUpdated: Emitted upon successful initiation.

deposit

function deposit(uint256 _value) external

Allows the seller to deposit base tokens and mint equivalent ERC-1155 tokens. @dev

• Only callable by the seller.
• Ensures the contract holds the deposited amount in ERC-20 tokens.
• Expects to have the seller's ERC-20 approval for the given value of base tokens.
• Uses ERC-20 calls to TransferFrom the value of base tokens to itself.

Parameters

Name	Type	Description
_value	uint256	The amount of base tokens to deposit.

makeOffer

function makeOffer(uint256 _offerId, uint256 baseValue, uint256 quoteValue) external

Allows a whitelisted offeror to submit an offer for the SalesOrder. @dev

• Can only be called by whitelisted offerors.
• Requires the contract to be in the INITIATED status.
• Ensures the configured active window is not passed.
• Ensures the _offerId is unique and unused.
• Records the offer details, including base and quote token values. *

Parameters

Name	Type	Description
_offerId	uint256	A unique identifier for the offer.
baseValue	uint256	The amount of base tokens involved in the offer.
quoteValue	uint256	The amount of quote tokens (or fiat equivalent) offered. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. - SalesOrderInvalidOfferId: Reverted when an invalid offer ID is encountered in a sales order. - TokenExchangeInactiveExchangeWindow: Reverted if exchange is called after the exchange window has passed. - SalesOrderInvalidStatus: Reverted when the status of a sales order is invalid. Emits: - OfferMade: Emitted once offer is made successfully.

acceptOffer

function acceptOffer(uint256 _offerId) external

Allows the seller to accept a submitted offer. @dev

• Can only be called by the seller.
• Ensures the offer exists and is in an ACTIVE state.
• Updates the offer status to ACCEPTED.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer being accepted. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. - SalesOrderInvalidOfferStatus: Reverted when an offer has an invalid status. Emits: - OfferAccepted: Emitted upon successful acceptance of offer.

initiateSale

function initiateSale(uint256 _offerId) external

Initiates the sale process for an accepted offer. @dev

• Ensures the offer exists and has been accepted.
• Validates the caller as the offeror.
• Depending on the exchange type:
  • For TOKEN_FOR_TOKEN:
    • Calculates the exchange ratio and executes the token swap
    • Updates the offer status to COMPLETED
  • For FIAT_FOR_TOKEN
    • Initiates the fiat exchange process.
    • Updates the offer status to IN_PROGRESS.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the accepted offer for which the sale is being initiated . Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. - SalesOrderInvalidOfferStatus: Reverted when an offer has an invalid status. Emits: - SaleInitiated: Emitted on successful initiation of sale.

completeSale

function completeSale(uint256 _offerId) external

Completes the sale process for a FIAT_FOR_TOKEN sale. @dev

• Ensures the offer is in the IN_PROGRESS state.
• Verifies the exchange type as FIAT_FOR_TOKEN.
• Marks the offer as COMPLETED.
• Internall calls _exchangeComplete to finalize the exchange.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which the sale is being completed. Error: - SalesOrderInvalidStatus: Reverted when the status of a sales order is invalid.. - SalesOrderInvalidOfferStatus: Reverted when an offer has an invalid status. Emits - SaleCompleted: Emitted upon successful completion of sale.

refuteSale

function refuteSale(uint256 _offerId) external

Allows the seller to refute an initiated sale. Useful in the event of a failure of payment-terms off-chain . @dev

• Can only be called by the seller.
• Ensures the offer is in the INITIATED_SALE state.
• Calls the internal _refute function to handle the refutation process.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which the sale is being refuted. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. - SalesOrderInvalidOfferStatus: Reverted when an offer has an invalid status. Emits: - SaleRefuted: Emitted on successful refutation of sale.

unrefuteSale

function unrefuteSale(uint256 _offerId) external

Allows the dispute resolver to unrefute a sale. Useful in the event on an undue/resolved refutation. @dev

• Can only be called by the designated dispute resolver.
• Calls _nullifyRefutation to reverse the refutation.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which a refute sale is being unrefuted. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. Emits: -SaleUnrefuted: Emitted on successful unrefute of sale.

cancelSale

function cancelSale(uint256 _offerId) external

Allows the dispute resolver to cancel a refuted sale. Useful in the event of a failed sale. @dev

• Can only be called by the dispute resolver.
• Calls _nullifyExchange to handle sale cancellation.
• Updates the offer status to CANCELLED.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which a refuted sale is being canceled. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. Emits: - SaleCancelled: Emitted on successful cancellation of sale.

withdraw

function withdraw(uint256 _value, address _to) external

Allows the seller to withdraw unsold deposited base tokens. @dev

• Can only be called by the seller.
• Ensures the sales period has ended.
• Checks the available balance of ERC-1155 tokens for withdrawal.
• Only allows withdrawal of tokens not locked in an active sale.
• Calls _withdraw to complete the withdrawal process.

Parameters

Name	Type	Description
_value	uint256	The amount of base tokens to withdraw.
_to	address	The address where the withdrawn tokens should be sent. Error: - SalesOrderUnauthorizedCaller: Reverted when an unauthorized caller attempts the operation. - TokenExchangeActiveExchangeWindow: Reverted when a withdraw request is attempted before the exchange window has closed. - TokenExchangeInsufficientBalance: Reverted when the request exceeds the available balance.