Solidity API

SalesOrder

The Sales Order is a trade contract enables tokenized asset sales, supporting both on-chain token payments and off-chain fiat settlements. It allows sellers to deposit tokens for sale, whitelisted buyers to make offers, and manages structured sale processes with mechanisms for refutations and dispute resolution.

A contract to facilitate token sales in exchange for fiat or tokens. Inherits from AbstractTokenExchange, Ownable, and ReentrancyGuard for enhanced functionality and security.

SELLER

address SELLER

Address of the seller depositing tokens for sale.

Offerors

mapping(address => bool) Offerors

Tracks authorized offeror addresses.

Status

_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
}

status

enum SalesOrder.Status status

OfferStatus

_Represents the status of an individual offer.

• NULL: No offer exists for the given ID.
• ACTIVE: The offer is active and not accepted yet.
• ACCEPTED: The offer has been accepted.
• INITIATED_SALE: The sale has been initiated for the offer.
• PROCESSED_FOR_SALE: The sale using this offer is completed.
• CANCELLED: The offer and corresponding sale was cancelled._

enum OfferStatus {
  NULL,
  ACTIVE,
  ACCEPTED,
  REJECTED,
  INITIATED_SALE,
  PROCESSED_FOR_SALE,
  CANCELLED
}

Offer

Represents an offer made by a potential buyer.

Parameters

Name	Type	Description

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

offers

mapping(uint256 => struct SalesOrder.Offer) offers

Mapping of offer IDs to their corresponding Offer data.

SalesOrderInvalidAddress

error SalesOrderInvalidAddress(address receivedAddress)

SalesOrderInvalidStatus

error SalesOrderInvalidStatus(enum SalesOrder.Status status)

SalesOrderInvalidOfferId

error SalesOrderInvalidOfferId(uint256 conditionId)

SalesOrderTransferFailed

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

SalesOrderUnauthorizedCaller

error SalesOrderUnauthorizedCaller(address sender)

SalesOrderInvalidOfferStatus

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

StatusUpdated

event StatusUpdated(enum SalesOrder.Status newStatus)

Emitted when the contract status is updated.

OfferMade

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

Emitted when a new offer is made.

OfferAccepted

event OfferAccepted(uint256 offerId)

Emitted when an offer is accepted.

SaleInitiated

event SaleInitiated(uint256 offerId)

Emitted when a sale is initiated for an offer.

SaleCompleted

event SaleCompleted(uint256 offerId)

Emitted when a sale is completed.

SaleRefuted

event SaleRefuted(uint256 offerId)

Emitted when a sale is refuted.

SaleCancelled

event SaleCancelled(uint256 offerId)

Emitted when a sale is cancelled.

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.

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.
• Emits a StatusUpdated event upon successful initiation.
• 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.

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.
• Emits an OfferMade event.

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.

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.
• Emits an OfferAccepted event upon successful acceptance.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer being accepted.

saleInitiate

function saleInitiate(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 PROCESSED_FOR_SALE
    • Emits a SaleCompleted event on successful completion.
  • For FIAT_FOR_TOKEN
    • Initiates the fiat exchange process.
    • Updates the offer status to INITIATED_SALE.
    • Emits a SaleInitiated event on successful completion.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the accepted offer for which the sale is being initiated .

salesComplete

function salesComplete(uint256 _offerId) external

Completes the sale process for a FIAT_FOR_TOKEN sale. @dev

• Ensures the offer is in the INITIATED_SALE state.
• Verifies the exchange type as FIAT_FOR_TOKEN.
• Marks the offer as PROCESSED_FOR_SALE.
• Internall calls _exchangeComplete to finalize the exchange.
• Emits a SaleCompleted event upon successful completion.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which the sale is being completed.

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.
• Emits a SaleRefuted event.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which the sale is being refuted.

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.
• Emits a SaleRefuted event.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which a refute sale is being unrefuted.

cancelSale

function cancelSale(uint256 _offerId) external

Allows the dispute resolver to cancel a refute 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.
• Emits a SaleCancelled event.

Parameters

Name	Type	Description
_offerId	uint256	The unique identifier of the offer for which a refuted sale is being canceled.

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.