Namespace: core

Functions

approveArbitrator

▸ approveArbitrator(escrowId, arbitrator, arbitratorFee, callbacks?): Promise<ApproveArbitratorParsedPayload>

Approves an arbitrator proposed by the other party (i.e. by seller if buyer proposed, by buyer if seller proposed). To ensure both agree to the same arbitrator and arbitrator fee, these parameters are included in the proposal.

Parameters

Name	Type	Description
escrowId	number	ID of the escrow
arbitrator	string	Arbitrator address
arbitratorFee	number	Arbitrator fee in %
callbacks?	IApproveArbitrationTransactionCallbacks	-

Returns

Promise<ApproveArbitratorParsedPayload>

Info about the approved arbitration

Defined in

core/approveArbitrator.ts:26

---

approveSettlement

▸ approveSettlement(escrowId, splitBuyer, splitSeller, callbacks?): Promise<ApproveSettlementParsedPayload>

Approves an offer to settle the payment between the buyer and the seller. To check that the user is really approving the right offer (i.e. to prevent on-chain front-running), the same offer parameters must be provided.

Parameters

Name	Type	Description
escrowId	number	ID of the escrow
splitBuyer	number	Share (%) of the escrow offered to the buyer
splitSeller	number	Share (%) of the escrow offered to the seller (buyer+seller must equal 100)
callbacks?	ISettlementApproveTransactionCallbacks	-

Returns

Promise<ApproveSettlementParsedPayload>

Info about the approved offer

Defined in

core/approveSettlement.ts:26

---

arbitrate

▸ arbitrate(escrowId, splitBuyer, splitSeller, callbacks?): Promise<ArbitrateParsedPayload>

Previously defined/agreed on arbitrator uses this to arbitrate the payment

Parameters

Name	Type	Description
escrowId	number	ID of the escrow to arbitrate
splitBuyer	number	What share of the escrow should go to the buyer (0 for release, 100 for refund)
splitSeller	number	What share of the escrow should go to the seller (buyer + seller must equal 100)
callbacks?	IArbitrateTransactionCallbacks	-

Returns

Promise<ArbitrateParsedPayload>

Info about the arbitration

Defined in

core/arbitrate.ts:24

---

calculateAmounts

▸ calculateAmounts(data, isSettledByArbitrator?): tShares

Calculates how the amounts of an escrow are split between all relevant parties. If settled by an arbitrator, this is considered in the calculation (arbitrator gets full share)

Parameters

Name	Type	Default value	Description
data	CalculateAmountsInput	undefined	Input data for the calculation (total amount in the escrow, and % splits)
isSettledByArbitrator	boolean	false	-

Returns

tShares

Shares of the escrow for each party (incl. fees) in token's or ETH's WEI

Defined in

core/calculateAmounts.ts:121

---

calculatePercentageFloat

▸ calculatePercentageFloat(percentage, amount): number

Parameters

Name	Type
percentage	number
amount	number

Returns

number

Defined in

core/calculateAmounts.ts:21

---

calculatePercentageInt

▸ calculatePercentageInt(percentage, amount): bigint

Parameters

Name	Type
percentage	number
amount	bigint

Returns

bigint

Defined in

core/calculateAmounts.ts:10

---

calculateStatus

▸ calculateStatus(ICalculateStatusParams): IEscrowStatus

Calculates detailed status of an scrow based on the provided inputs

Parameters

Name	Type	Description
ICalculateStatusParams	ICalculateStatusParams	Escrow parameters necessary to calculate the status

Returns

IEscrowStatus

Calculated details

Defined in

core/calculateStatus.ts:26

---

challenge

▸ challenge(escrowId, callbacks?): Promise<ChallengeParsedPayload>

Sends a challenge and returns the escrow data.

Parameters

Name	Type	Description
escrowId	number	Escrow ID
callbacks?	IChallengeTransactionCallbacks	-

Returns

Promise<ChallengeParsedPayload>

Escrow data after the challenge

Defined in

core/challenge.ts:22

---

claim

▸ claim(escrowId, callbacks?): Promise<ClaimParsedPayload>

Claims a share from the escrow. To save everyone's gas costs, it claims balances and fees for all parties that are eligible for it.

Parameters

Name	Type	Description
escrowId	number	ID of the escrow to claim
callbacks?	IClaimTransactionCallbacks	-

Returns

Promise<ClaimParsedPayload>

Claimed amounts (in token's or ETH's WEI) per party)

Defined in

core/claim.ts:19

---

claimMultiple

▸ claimMultiple(escrowIds, callbacks?): Promise<MultipleClaimParsedPayload>

Claims multiple shares of an escrow at the same time. To save everyone's gas costs, it claims balances and fees for all parties that are eligible for it. The contract will check for each escrow if shares are indeed claimable. If not, the transaction will revert and return an error. The gas cost of this action grows almost linearly with each additional escrow, therefore it will set an appropriate gas limit if necessary.

Parameters

Name	Type	Description
escrowIds	number[]	List of escrows to claim. Indexer's getClaimableEscrow() function provides an easy way to get a predigested list for this action.
callbacks?	IClaimTransactionCallbacks	-

Returns

Promise<MultipleClaimParsedPayload>

Amounts (in WEI) claimed per party and escrow

Defined in

core/claimMultiple.ts:25

---

getEscrowData

▸ getEscrowData(escrowId): Promise<IGetEscrowData>

Get all information about an escrow: Escrow details, Token, Arbitration, Settlement

Returns null if some attributes, like arbitration or settlement are not specified

Parameters

Name	Type	Description
escrowId	number	ID of the escrow

Returns

Promise<IGetEscrowData>

All details about the escrowed payment

Example

// The most simple escrow for 1 ETH with no arbitrator or marketplace returns something like this:
{
   challengePeriod: 1209600,                           // Challenge period extension in seconds
   challengePeriodStart: "2024-09-12T15:07:45.000Z",   // Start of the current challenge period
   challengePeriodEnd: "2024-09-26T15:07:45.000Z",     // End of the current challenge period
   status: {
      state: "Released",
      latestChallengeBy: null,
      latestSettlementOfferBy: null,
      claimed: true                                    // Claimed from the escrow (by buyer's Release in this case)
   },
   escrowId: 2,
   amount: "100000000000000000",                       // Amount in wei
   marketplace: null,
   buyer: "0x8A62....D1D8",                            // Shortened in docs, but otherwise returned in full
   seller: "0xf463b....0560",
   token: {
      address: null,
      decimals: 18,                                    // Use pow(10, <this>) to convert to standard units
      symbol: "ETH"
   },
   paymentReference: "",                               // A text reference, e.g. order ID
   splitMarketplace: 0,                                // Marketplace fee
   splitBuyer: 0,                                      // Buyer's share in current status (0 for Paid, Released)
   splitSeller: 100,                                   // Seller's share in current status (100 for Paid, Released)
   splitProtocol: 0.69,                                // Protocol fee
   consensusBuyer: 1,                                  // Buyer's consensus (see contracts docs for how this works)
   consensusSeller: 1,                                 // Seller's consensus
   arbitration: null,
   settlement: null,
   connectedUser: "buyer",
   walletAddress: "0x8A62....D1D8"
}

// An escrow with 100 USDT, an arbitrator and marketplace with fees, which was challenged by buyer and has a settlement offer from the seller looks like this:
{
   challengePeriod: 604800,
   challengePeriodStart: "2024-09-12T15:19:14.000Z",
   challengePeriodEnd: "2024-09-26T15:19:14.000Z",
   status: {
      state: "Released",
      latestChallengeBy: null,
      latestSettlementOfferBy: null,
      claimed: true
   },
   escrowId: 3,
   amount: 100000000,
   marketplace: "0x696207De45d897d5a353af3c45314a2F852d5B63",
   buyer: "0xF257DD5731A679E6642FCd9c53e4e26A1206527e",
   seller: "0xf463b32cad657fe03921014d99490A0a58290560",
   token: {
      address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      symbol: "USDT",
      decimals: 6
   },
   paymentReference: "order #1337",
   splitMarketplace: 10,
   splitBuyer: 0,
   splitSeller: 100,
   splitProtocol: 0.69,
   consensusBuyer: 1,
   consensusSeller: 1,
   arbitration: {
      arbitrator: "0x59f56CFC88E5660b7D68C4797c6484168eC8E068",
      consensusSeller: true,
      consensusBuyer: true,
      arbitrated: false,
      arbitratorFee: 2
   },
   settlement: null,
   connectedUser: "buyer",
   walletAddress: "0xf257dd5731a679e6642fcd9c53e4e26a1206527e"
}

Throws

Error if escrow id doesn't exist.

Defined in

core/getEscrowData.ts:276

---

getProtocolFee

▸ getProtocolFee(): Promise<number>

Retrieves information about the protocol fee and returns its percentage. If you need to have it in bips, multiply by 100.

Returns

Promise<number>

The protocol fee in percentage

Defined in

core/getProtocolFee.ts:13

---

getSingleBalance

▸ getSingleBalance(escrowId): Promise<IBalanceDetailed>

Calculates how much of the defined escrow belongs to the connected account should the escrow be claimed in its current status

Parameters

Name	Type	Description
escrowId	number	ID of the escrow

Returns

Promise<IBalanceDetailed>

User's balance in the escrow

Defined in

core/getSingleBalance.ts:11

---

getTokenInfo

▸ getTokenInfo(tokenAddress?): Promise<IToken>

Gets info of an ERC20 token based on its address.

Parameters

Name	Type	Default value	Description
tokenAddress	any	ethers.ZeroAddress	Address of the token on Arbitrum One blockchain

Returns

Promise<IToken>

Token address, symbol, and no. of its decimals

Throws

Error if token info doesn't exist on this address or the token address couldn't be parsed.

Defined in

core/getTokenInfo.ts:29

---

offerSettlement

▸ offerSettlement(escrowId, splitBuyer, splitSeller, callbacks?): Promise<OfferSettlementParsedPayload>

Sends an offer to settle the payment arbitrarily between the buyer and the seller. The other party must confirm the settlement in order for it to be executed.

Parameters

Name	Type	Description
escrowId	number	Id of the escrow
splitBuyer	number	Split offered to the buyer (%)
splitSeller	number	Split offered to the seller (%)
callbacks?	ISettlementOfferTransactionCallbacks	-

Returns

Promise<OfferSettlementParsedPayload>

The percentages of the payment split between the buyer and seller, by who it was offered and when

Defined in

core/offerSettlement.ts:25

---

pay

▸ pay(paymentProps, callbacks?): Promise<PayParsedPayload>

Deposits a payment into an escrow and returns its data. The function automagically connects user's wallet, checks for the balance in the selected token, asks for approval, and if the address was provided in ENS format, resolves that to ETH address.

Parameters

Name	Type	Description
paymentProps	IPaymentProps	Payment details
callbacks?	IPayTransactionCallbacks	Pass code to any of these to be executed when the respective step takes place in the wallet

Returns

Promise<PayParsedPayload>

Details of the payment as returned by the contract's Pay event

Example

// The most simple example of 0.1 ETH payment with 2 week challenge period and with no arbitrator or a marketplace
await Unicrow.core.pay({
    seller: "0xf463b32cad657fe03921014d99490A0a58290560",
    amount: 0.1,
    challengePeriod: 86400 * 14, // 14 days
  }, {
  confirmed: (payload) {
    // print out payload
  }
})

// Console output
{
   transactionHash: "0xf7d347866aaa583f7a8e63457f4afed85f40932c35ac8ffafc2a1c1dc31b19f6",
   blockNumber: 252780689,
   paidAt: "2024-09-12T15:07:45.000Z",
   escrowId: 2,
   arbitrator: null,
   arbitratorFee: 0,
   buyer: "0x8A62e7F471ad5B5081d4A864580edd944525D1D8",
   seller: "0xf463b32cad657fe03921014d99490A0a58290560",
   challengePeriod: 1209600,
   challengePeriodExtension: 1209600,
   challengePeriodStart: "2024-09-12T15:07:45.000Z",
   challengePeriodEnd: "2024-09-26T15:07:45.000Z",
   marketplace: null,
   marketplaceFee: 0,
   tokenAddress: null,
   paymentReference: "",
   claimed: false,
   consensusBuyer: 0,
   consensusSeller: 1,
   splitBuyer: 0,
   splitSeller: 100,
   splitMarketplace: 0,
   splitProtocol: 0.69,
   amount: "100000000000000000",
   amountBuyer: "0",
   amountSeller: "99310000000000000",
   amountMarketplace: "0",
   amountArbitrator: "0",
   amountProtocol: "690000000000000"
}

// Another example using all the available payment parameters: 
//   - tokenAddress to send 100 USDT
//   - setting a different buyer 
//   - a marketplace and an arbitrator with fees 
//   - different challenge period and challenge period extension
//   - adding a payment reference
await Unicrow.core.pay({
    seller: "0xf463b32cad657fe03921014d99490A0a58290560",
    tokenAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    amount: 100,
    buyer: "0xF257DD5731A679E6642FCd9c53e4e26A1206527e",
    arbitrator: "0x59f56CFC88E5660b7D68C4797c6484168eC8E068",
    arbitratorFee: 2,
    marketplace: "0x696207De45d897d5a353af3c45314a2F852d5B63",
    marketplaceFee: 10,
    challengePeriod: 86400 * 14, // 14 days
    challengePeriodExtension: 86400 * 7, // 7 days
    paymentReference: "order #1337"
   }, {
  confirmed: (payload) {
    // print out payload
  }
})

// Output
{
   transactionHash: "0x51766a44fb247f33e6caf31dbe01579e100dd0b96020c78358b263d86c30c96d",
   blockNumber: 252783397,
   paidAt: "2024-09-12T15:19:14.000Z",
   escrowId: 3,
   arbitrator: "0x59f56CFC88E5660b7D68C4797c6484168eC8E068",
   arbitratorFee: 2,
   buyer: "0xF257DD5731A679E6642FCd9c53e4e26A1206527e",
   seller: "0xf463b32cad657fe03921014d99490A0a58290560",
   challengePeriod: 1209600,
   challengePeriodExtension: 604800,
   challengePeriodStart: "2024-09-12T15:19:14.000Z",
   challengePeriodEnd: "2024-09-26T15:19:14.000Z",
   marketplace: "0x696207De45d897d5a353af3c45314a2F852d5B63",
   marketplaceFee: 10,
   tokenAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
   paymentReference: "order #1337",
   claimed: false,
   consensusBuyer: 0,
   consensusSeller: 1,
   splitBuyer: 0,
   splitSeller: 100,
   splitMarketplace: 10,
   splitProtocol: 0.69,
   amount: "100000000",
   amountBuyer: "0",
   amountSeller: "87310000",
   amountMarketplace: "10000000",
   amountArbitrator: "2000000",
   amountProtocol: "690000"
}

Throws

Error if the user doesn't connect wallet, doesn't approve token spending, doesn't have a a sufficient amount, or if any of the parameters has incorrect format

Defined in

core/pay.ts:130

---

proposeArbitrator

▸ proposeArbitrator(escrowId, arbitrator, arbitratorFee, callbacks?): Promise<ProposalArbitratorParsedPayload>

One of the parties (buyer or seller) can call this to propose an arbitrator for an escrow that has no arbitrator defined.

Parameters

Name	Type	Description
escrowId	number	Id of an escrow for which the arbitrator is being proposed
arbitrator	string	Arbitrator's address
arbitratorFee	number	Arbitrator's fee in % (can be 0)
callbacks?	IProposeArbitrationTransactionCallbacks	Pass code to any of these to be executed when the respective step takes place in the wallet

Returns

Promise<ProposalArbitratorParsedPayload>

Info about the proposed arbitrator, his fee and who proposed it

Defined in

core/proposeArbitrator.ts:22

---

refund

▸ refund(escrowId, callbacks?): Promise<string>

Refunds 100% of the buyer payment (all fees are waived), returns transactions' hash. Can only be called by the seller.

Parameters

Name	Type	Description
escrowId	number	ID of the escrow to refund
callbacks?	IRefundTransactionCallbacks	-

Returns

Promise<string>

transaction hash

Throws

Error if account is not connected or if called in an invalid state (e.g. already claimed / not called by seller)

Defined in

core/refund.ts:19

---

release

▸ release(escrowId, callbacks?): Promise<ReleaseParsedPayload>

Release the escrow to the seller and to all other parties that charge a fee from it.

Parameters

Name	Type	Description
escrowId	number	ID of the escrow to release
callbacks?	IReleaseTransactionCallbacks	-

Returns

Promise<ReleaseParsedPayload>

Payload with all info about the escrow, including how much was sent to whom (incl. fees)

Throws

If account is not connected or if called in invalid state (e.g. already claimed / not called by the buyer)

Defined in

core/release.ts:19