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? | IArbitrationTransactionCallbacks | - |
Returns
Promise<ApproveArbitratorParsedPayload>
Info about the approved arbitration
Defined in
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
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? | IArbitrationTransactionCallbacks | - |
Returns
Promise<ArbitrateParsedPayload>
Info about the arbitration
Defined in
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
Shares of the escrow for each party (incl. fees) in token's or ETH's WEI
Defined in
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
Calculated details
Defined in
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
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
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
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
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: "2023-01-27T16:31:07.000Z", // Start of the current challenge period
challengePeriodEnd: "2023-02-10T16:31:07.000Z", // End of the current challenge period
status: {
state: "Paid", // Paid, CP not ended, or refunded, etc.
latestChallengeBy: null,
latestSettlementOfferBy: null,
claimed: false // Hasen't been claimed from the escrow
},
escrowId: 593,
amount: "1000000000000000000", // Amount in wei
marketplace: null,
buyer: "0xD024....5861", // Shortened in docs, but otherwise returned in full
seller: "0xA981....041D",
token: {
address: null,
decimals: 18, // Use pow(10, this) to convert to standard units
symbol: "ETH"
},
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: 0, // Buyer's consensus (see contracts docs for how this works)
consensusSeller: 1, // Seller's consensus
arbitration: null,
settlement: null,
connectedUser: "buyer",
connectedWallet: "0xd024....5861"
}
// An escrow with 1,000 USDT, an arbitrator and marketplace with fees, which was challenged by buyer and has a settlement offer from the seller looks like this:
{
challengePeriod: 1209600,
challengePeriodStart: "2023-02-10T16:32:33.000Z",
challengePeriodEnd: "2023-02-24T16:32:33.000Z",
status: {
state: "Challenged",
latestChallengeBy: "buyer", // Buyer challenged
latestSettlementOfferBy: "seller", // Seller offered a settlement (see below for details)
claimed: false
},
escrowId: 594,
amount: "1000000000",
marketplace: "0xf8C0....f187", // This address will receive a marketplace fee (below)
buyer: "0xD0244....5861",
seller: "0xA9813....041D",
token: {
address: "0xFd08....Cbb9", // USDT Arbitrum address
symbol: "USDT", // Symbol from the token's contract
decimals: 6
},
splitMarketplace: 5, // 5% marketplace fee (not paid if challenge is successful or payment is refunded)
splitBuyer: 100, // Since buyer challenged, their split is 100
splitSeller: 0, // Since buyer challenged, seller's split is 0
splitProtocol: 0.69, // Protocol fee (not paid if challenge is successful)
consensusBuyer: 1,
consensusSeller: -1, // This means seller is currently challenged 1st time
arbitration: {
arbitrator: "0x3C86....9B66", // Address of the proposed or defined arbitrator
consensusSeller: true, // Whether seller agreed (implicitly or explicitly) on the arbitrator
consensusBuyer: true, // If both buyer and seller consensus is true, the arbitrator is set
arbitrated: false, // The arbitrator hasn't stepped in yet
arbitratorFee: 2 // Arbitrator's fee in %
},
settlement: {
latestSettlementOfferAddress: "0xA981....041D", // Who sent the latest settlement offer
latestSettlementOfferBuyer: 20, // Buyer was offered to get 20% back
latestSettlementOfferSeller: 80 // Seller asked to receive 80% (minus fees)
},
connectedUser: "seller",
connectedWallet: "0xa9813....041d"
}
Throws
Error if escrow id doesn't exist.
Parameters
| Name | Type | Description |
|---|---|---|
escrowId | number | ID of the escrow |
Returns
Promise<IGetEscrowData>
All details about the escrowed payment
Defined in
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
getSingleBalance
▸ getSingleBalance(escrowId): Promise<IBalanceWithTokenInfo>
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<IBalanceWithTokenInfo>
User's balance in the escrow
Defined in
getTokenInfo
▸ getTokenInfo(tokenAddress?): Promise<IToken>
Gets info of an ERC20 token based on its address.
Throws
Error if token info doesn't exist on this address or the token address couldn't be parsed.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
tokenAddress | any | ETH_ADDRESS | Address of the token on Arbitrum One blockchain |
Returns
Promise<IToken>
Token address, symbol, and no. of its decimals
Defined in
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
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.
Example
// The most simple example of 1 ETH payment with 2 week challenge period and with no arbitrator or a marketplace
await unicrowSdk.ui.pay({
seller: "0xA98135151f8dCd5632A63CC6358f5684c62B041D",
amount: 1,
challengePeriod: ONE_DAY_IN_SEC * 14
}, {
confirmed: (payload) {
// print out payload
}
})
// Console output
{
name: "Pay",
transactionHash: "0x965b682d76617355e701ad5e3ece8760f8b0e76815d7d817ee84a8cbdb1f4cd7",
blockNumber: 7956,
paidAt: "2023-01-27T16:31:07.000Z",
escrowId: 593,
arbitrator: null,
arbitratorFee: 0,
buyer: "0xD0244c3B17792390010581D54951ba049dF85861",
seller: "0xA98135151f8dCd5632A63CC6358f5684c62B041D",
challengePeriod: 1209600,
challengePeriodExtension: 1209600,
challengePeriodStart: "2023-01-27T16:31:07.000Z",
challengePeriodEnd: "2023-02-10T16:31:07.000Z",
marketplace: null,
marketplaceFee: 0,
tokenAddress: null,
claimed: false,
consensusBuyer: 0,
consensusSeller: 1,
splitBuyer: 0,
splitSeller: 100,
splitMarketplace: 0,
splitProtocol: 0.69,
amount: "1000000000000000000",
amountBuyer: "0",
amountSeller: "993100000000000000",
amountMarketplace: "0",
amountArbitrator: "0",
amountProtocol: "6900000000000000"
}
// Another example of 1,000 USDT payment with a marketplace and an arbitrator and a different challenge period and extension
await unicrowSdk.ui.pay({
seller: "0xA98135151f8dCd5632A63CC6358f5684c62B041D",
tokenAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
amount: 1000,
challengePeriod: ONE_DAY_IN_SEC * 14,
challengePeriod: ONE_DAY_IN_SEC * 7,
marketplace: "0xf8C03F09b4f53FDc05b57c7846da5F428798f187",
marketplaceFee: 5,
arbitrator: "0x3C86F543e64810E1d843809B2b70a4FDcC3b9B66",
arbitratorFee: 2
}, {
confirmed: (payload) {
// print out payload
}
})
// Output
{
name: "Pay",
transactionHash: "0xb37166392207bbd7e89858606e3b88d11d9d00fb1f508bc0e81dc8a3a990c69f",
blockNumber: 7958,
paidAt: "2023-01-27T16:32:33.000Z",
escrowId: 594,
arbitrator: "0x3C86F543e64810E1d843809B2b70a4FDcC3b9B66",
arbitratorFee: 2,
buyer: "0xD0244c3B17792390010581D54951ba049dF85861",
seller: "0xA98135151f8dCd5632A63CC6358f5684c62B041D",
challengePeriod: 1209600,
challengePeriodExtension: 604800,
challengePeriodStart: "2023-01-27T16:32:33.000Z",
challengePeriodEnd: "2023-02-10T16:32:33.000Z",
marketplace: "0xf8C03F09b4f53FDc05b57c7846da5F428798f187",
marketplaceFee: 5,
tokenAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
claimed: false,
consensusBuyer: 0,
consensusSeller: 1,
splitBuyer: 0,
splitSeller: 100,
splitMarketplace: 5,
splitProtocol: 0.69,
amount: "1000000000",
amountBuyer: "0",
amountSeller: "923100000",
amountMarketplace: "50000000",
amountArbitrator: "20000000",
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
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
Defined in
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? | IArbitrationTransactionCallbacks | 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
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.
Throws
Error if account is not connected or if called in an invalid state (e.g. already claimed / not called by seller)
Parameters
| Name | Type | Description |
|---|---|---|
escrowId | number | ID of the escrow to refund |
callbacks? | IRefundTransactionCallbacks | - |
Returns
Promise<string>
transaction hash
Defined in
release
▸ release(escrowId, callbacks?): Promise<ReleaseParsedPayload>
Release the escrow to the seller and to all other parties that charge a fee from it.
Throws
If account is not connected or if called in invalid state (e.g. already claimed / not called by the buyer)
Parameters
| Name | Type | Description |
|---|---|---|
escrowId | number | if 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)