Integration

The ebox On-Chain Escrow revolves around the concept of "boxes", where each box represents a pending transaction. Boxes can be created, cleared or cancelled.
  • Creating a box equals depositing funds into the contract as sender, and setting parameters for retrieval: Recipient address, funds to be requested in return (if any), passphrase.
  • Clearing a box retrieves the deposited funds, only possible for the legitimate recipient as specified by the sender. The correct passphrase is required, and requested funds (if any) need to be held.
  • Cancelling a box is what a user needs to do when there's been a mistake while sending (wrong recipient address, wrong asset, wrong amount of funds).
For each of these operations, increased privacy is available as an optional feature. Requesting funds (OTC trading) is only possible when it is not being used.
Contract addresses for all supported blockchains and the contract ABI are at the bottom of this page.

Functions Overview

The following functions execute the main escrow functionality:
Getter functions for retrieving box(es) data:
The ERC20Interface type used here is the standard ERC-20 token interface, conforming to the OpenZeppelin IERC20 interface.

Main Functions

createBox

Creates a box, depositing funds into the contract for later retrieval by the designated recipient, while optionally also requesting funds.
createBox(
address recipient,
ERC20Interface sendToken,
uint sendValue,
ERC20Interface requestToken,
uint requestValue,
bytes32 passHashHash
)

Arguments:

  • addressrecipient
    • Address of the recipient legitimated to clear the box
  • ERC20InterfacesendToken
    • Address of the ERC-20 token to be sent
    • 0x0000000000000000000000000000000000000000 for using the chain coin (ETH for Ethereum, BNB for BSC, MATIC for Polygon etc)
  • uintsendValue
    • Amount of funds to be sent, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
  • ERC20InterfacerequestToken
    • Address of the ERC-20 token to be requested
    • Irrelevant if just sending, not requesting
      • In that case, set requestValue to 0 (see below)
  • uintrequestValue
    • Amount of funds to be requested, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
    • Can be zero (when just sending, not requesting)
  • bytes32passHashHash
    • Passphrase required from the recipient when clearing the box
    • Hashed twice using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3(web3.utils.sha3("passphrase"))

clearBox

Clears a box that was previously created by someone else, requiring the correct passphrase and, optionally, holding the funds requested by the sender.
clearBox(
uint boxIndex,
bytes32 passHash
)

Arguments:

  • uintboxIndex
  • bytes32passHash
    • Passphrase set by the sender when creating the box
    • Hashed once using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3("passphrase")

cancelBox

Cancels one's own box, not requiring the passphrase or holding requested funds (if any).
cancelBox(
uint boxIndex
)

Arguments:

createBoxWithPrivacy

Creates a box with increased privacy, depositing funds into the contract for later retrieval by the designated recipient.
createBoxWithPrivacy(
bytes32 recipientHash,
ERC20Interface sendToken,
uint sendValue,
bytes32 passHashHash
)

Arguments:

  • bytes32recipientHash
    • Address of the recipient legitimated to clear the box
    • Hashed once using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3("address")
  • ERC20InterfacesendToken
    • Address of the ERC-20 token to be sent
    • 0x0000000000000000000000000000000000000000 for using the chain coin (ETH for Ethereum, BNB for BSC, MATIC for Polygon etc)
  • uintsendValue
    • Amount of funds to be sent, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
  • bytes32passHashHash
    • Passphrase required from the recipient when clearing the box
    • Hashed twice using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3(web3.utils.sha3("passphrase"))

clearBoxWithPrivacy

Clears a box with increased privacy that was previously created by someone else, requiring the correct passphrase.
clearBoxWithPrivacy(
uint boxIndex,
bytes32 passHash
)

Arguments:

cancelBoxWithPrivacy

Cancels one's own box with increased privacy, not requiring the passphrase.
cancelBoxWithPrivacy(
uint boxIndex
)

Arguments:

Getter Functions

getBoxesOutgoing

Returns a list of indexes of all outgoing boxes for the calling address (pending and fulfilled), to be used with getBox.
getBoxesOutgoing()

Returns:

  • uint[]
    • Array of outgoing box indexes

getBoxesIncoming

Returns a list of indexes of all incoming boxes for the calling address (pending and fulfilled), to be used with getBox.
getBoxesIncoming()

Returns:

  • uint[]
    • Array of incoming box indexes

getBox

Returns the transaction data for the specified box.
getBox(
uint boxIndex
)

Arguments:

Returns:

getBoxesOutgoingWithPrivacy

Returns a list of indexes of all outgoing boxes with increased privacy for the calling address (pending and fulfilled), to be used with getBoxWithPrivacy.
getBoxesOutgoingWithPrivacy()

Returns:

getBoxesIncomingWithPrivacy

Returns a list of indexes of all incoming boxes with increased privacy for the calling address (pending and fulfilled), to be used with getBoxWithPrivacy.
getBoxesIncomingWithPrivacy()

Returns:

getBoxWithPrivacy

Returns the transaction data for the specified box with increased privacy.
getBoxWithPrivacy(
uint boxIndex
)

Arguments:

Returns:

Data Structures

These datasets are returned from the respective getter functions, carrying all relevant information about a pending or fulfilled transaction.
The ERC20Interface type used here is the standard ERC-20 token interface, conforming to the OpenZeppelin IERC20 interface.

Box

struct Box {
address payable sender;
address recipient;
bytes32 passHashHash;
ERC20Interface sendToken;
uint sendValue;
ERC20Interface requestToken;
uint requestValue;
uint timestamp;
bool taken;
}
  • addresssender
    • Address of the sender, able to cancel the box
  • addressrecipient
    • Address of the recipient legitimated to clear the box
  • bytes32passHashHash
    • Passphrase required from the recipient when clearing the box
    • Hashed twice using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3(web3.utils.sha3("passphrase"))
  • ERC20InterfacesendToken
    • Address of the ERC-20 token to be sent
    • 0x0000000000000000000000000000000000000000 for using the chain coin (ETH for Ethereum, BNB for BSC, MATIC for Polygon etc)
  • uintsendValue
    • Amount of funds to be sent, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
  • ERC20InterfacerequestToken
    • Address of the ERC-20 token to be requested
    • Irrelevant if just sending, not requesting
      • In that case, requestValue is 0 (see below)
  • uintrequestValue
    • Amount of funds to be requested, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
    • Can be zero (when just sending, not requesting)
  • uinttimestamp
    • Unix timestamp at which the box was created, in seconds
  • booltaken
    • Indicates whether the transaction has been fulfilled (cleared or cancelled)

BoxWithPrivacy

struct BoxWithPrivacy {
bytes32 senderHash;
bytes32 recipientHash;
bytes32 passHashHash;
ERC20Interface sendToken;
uint sendValue;
uint timestamp;
bool taken;
}
  • bytes32senderHash
    • Address of the sender, able to cancel the box
    • Hashed once using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3("address")
  • bytes32recipientHash
    • Address of the recipient legitimated to clear the box
    • Hashed once using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3("address")
  • bytes32passHashHash
    • Passphrase required from the recipient when clearing the box
    • Hashed twice using Keccak / SHA-3 hashing algorithm
      • web3.js example: web3.utils.sha3(web3.utils.sha3("passphrase"))
  • ERC20InterfacesendToken
    • Address of the ERC-20 token to be sent
    • 0x0000000000000000000000000000000000000000 for using the chain coin (ETH for Ethereum, BNB for BSC, MATIC for Polygon etc)
  • uintsendValue
    • Amount of funds to be sent, in Wei
      • 1 ETH = 10¹⁸ Wei, same for tokens with 18 decimals
  • uinttimestamp
    • Unix timestamp at which the box was created, in seconds
  • booltaken
    • Indicates whether the transaction has been fulfilled (cleared or cancelled)

Contract Implementation

Address

Mainnet
Testnet
Ethereum: 0x501AC1D6103fB2643f2cB93985baAac6f81d1Bc9
BSC: 0x98F8E39032B4dBEC2235B68Bd7CC2505D3793161
Polygon: 0xbD1E729074A14348c78E39b56992f54f0b5d37Ec
Reef Chain: 0x9928e7A8e766E1E5Aa3f7C450bd4D513F8D9B141
Moonriver: 0x33840024177A7DacA3468912363BeD8b425015c5
Moonbeam: 0x33840024177A7DacA3468912363BeD8b425015c5
Rinkeby: 0xAAa491Cf3cA23D59a77eB56Ab487169F4B49e4e2
BSC Testnet: 0xF559344bF9A51bF778fB0Ff38cc690bAF7E61081
Polygon Testnet: 0x6c1cd6434B5Ee4A75605981387cBb3cdDc5596d0
Reef Testnet: 0xE21Dce52e291A788956A4Fd7446F9dc4Eb1f0CF4

ABI

[{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"}],"name":"cancelBox","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"}],"name":"cancelBoxWithPrivacy","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"},{"internalType":"bytes32","name":"passHash","type":"bytes32"}],"name":"clearBox","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"},{"internalType":"bytes32","name":"passHash","type":"bytes32"}],"name":"clearBoxWithPrivacy","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"address","name":"recipient","type":"address"},{"internalType":"contract ERC20Interface","name":"sendToken","type":"address"},{"internalType":"uint256","name":"sendValue","type":"uint256"},{"internalType":"contract ERC20Interface","name":"requestToken","type":"address"},{"internalType":"uint256","name":"requestValue","type":"uint256"},{"internalType":"bytes32","name":"passHashHash","type":"bytes32"}],"name":"createBox","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"bytes32","name":"recipientHash","type":"bytes32"},{"internalType":"contract ERC20Interface","name":"sendToken","type":"address"},{"internalType":"uint256","name":"sendValue","type":"uint256"},{"internalType":"bytes32","name":"passHashHash","type":"bytes32"}],"name":"createBoxWithPrivacy","outputs":[],"stateMutability":"payable","type":"function"},{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"}],"name":"getBox","outputs":[{"components":[{"internalType":"address payable","name":"sender","type":"address"},{"internalType":"address","name":"recipient","type":"address"},{"internalType":"bytes32","name":"passHashHash","type":"bytes32"},{"internalType":"contract ERC20Interface","name":"sendToken","type":"address"},{"internalType":"uint256","name":"sendValue","type":"uint256"},{"internalType":"contract ERC20Interface","name":"requestToken","type":"address"},{"internalType":"uint256","name":"requestValue","type":"uint256"},{"internalType":"uint256","name":"timestamp","type":"uint256"},{"internalType":"bool","name":"taken","type":"bool"}],"internalType":"struct ethbox.Box","name":"","type":"tuple"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"boxIndex","type":"uint256"}],"name":"getBoxWithPrivacy","outputs":[{"components":[{"internalType":"bytes32","name":"senderHash","type":"bytes32"},{"internalType":"bytes32","name":"recipientHash","type":"bytes32"},{"internalType":"bytes32","name":"passHashHash","type":"bytes32"},{"internalType":"contract ERC20Interface","name":"sendToken","type":"address"},{"internalType":"uint256","name":"sendValue","type":"uint256"},{"internalType":"uint256","name":"timestamp","type":"uint256"},{"internalType":"bool","name":"taken","type":"bool"}],"internalType":"struct ethbox.BoxWithPrivacy","name":"","type":"tuple"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"getBoxesIncoming","outputs":[{"internalType":"uint256[]","name":"","type":"uint256[]"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"getBoxesIncomingWithPrivacy","outputs":[{"internalType":"uint256[]","name":"","type":"uint256[]"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"getBoxesOutgoing","outputs":[{"internalType":"uint256[]","name":"","type":"uint256[]"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"getBoxesOutgoingWithPrivacy","outputs":[{"internalType":"uint256[]","name":"","type":"uint256[]"}],"stateMutability":"view","type":"function"}]