Linkdrop-p2p-sdk NPM

Linkdrop P2P SDK (V3)

Import and initialize SDK

import { LinkdropP2P } from 'linkdrop-p2p-sdk'

const baseUrl = "https://p2p.linkdrop.io" // baseUrl is the host to be used to generate claim URLs. Required
const apiKey = "spfurjdmvfkdlfo" // apiKey is the string parameter that will be passed to headers as Bearer token ("authorization" header). Not required. Default value: null
const apiUrl = "https://api.myurl.com" // apiUrl is the string parameter that will be used as request url prefix for endpoints. Not required. Default value: https://escrow-api.linkdrop.io/v2
const getRandomBytes = (length) => { 
  return new Uint8Array(crypto.randomBytes(length));
} // To avoid using and linking native crypto libraries, we ask to pass a random bytes generation function. Required

const sdk = LinkdropP2P({
  apiKey,
  baseUrl,
  apiUrl,
  getRandomBytes
})

Sender methods

Creating claim link

1. Initialize claim link object:
Learn more about the claimLink object in the ClaimLink section

const from = "0x2331bca1f2de4661ed88a30c99a7a9449aa84195" // Sender's Ethereum address
const token = "0x0fa8781a83e46826621b3bc094ea2a0212e71b23" // token contract address
const tokenType = "ERC1155" // one of "NATIVE" | "ERC20" | "ERC721" | "ERC1155"
const chainId = 80001 // network chain ID
const amount = "1000000" // atomic amount of tokens that sender wants to send (before fees). Not required for 'ERC721' tokens
const expiration = "1695985897077" // unix timestamp after which the claim link will expire and amount will be sent back to sender unless it was claimed before. Optional param, it not passed, it's going to be set to 15 days from now,
const tokenId = "1" // ID of token. Required for "ERC721" and "ERC1155"

const claimLink = await sdk.createClaimLink({
  from,
  token,
  amount,
  expiration,
  chainId,
  tokenType,
  tokenId
})

You can update amount for "NATIVE", "ERC20", and "ERC1155" tokens

const { amount, feeAmount, totalAmount, feeToken } = await claimLink.updateAmount(amount)

Methods createClaimLink and updateAmount will throw an error if amount is not valid according to limits.

To define the minimum and maximum limit of amount that can be sent via link, use the getLimits method. Method is not available for ERC721 or ERC1155 tokens

const token = "0x0fa8781a83e46826621b3bc094ea2a0212e71b23" // token contract address. Not required if tokenType is NATIVE
const tokenType = "ERC20" // one of "NATIVE" | "ERC20".
const chainId = 80001 // network chain ID

const { minTransferAmount, maxTransferAmount } = await sdk.getLimits({
  token,
  tokenType,
  chainId
})

2a. Deposit USDC tokens to escrow contract via EIP-3009 (transferWithAuthorization) :
To avoid asking for sender private key directly, we ask to pass a function that generates a EIP712 signature using Sender's private key. The function should be similar to ethers signer.signTypedData - https://docs.ethers.org/v6/api/providers/#Signer-signTypedData

const signTypedData = (domain, types, message) => signer.signTypedData(domain, types, message)
const { claimUrl, transferId, txHash } = await claimLink.depositWithAuthorization({ signTypedData })

2b. Deposit native tokens (ETH/MATIC), ERC721, ERC1155 or ERC20 tokens to escrow contract via direct call :
To avoid asking for sender private key directly, we ask to pass a function that signs and sends Ethereum transaction. The function should be similar to ethers signer.sendTransaction - https://docs.ethers.org/v6/api/providers/#Signer-signTypedData

const sendTransaction = async ({ to, value, data }) => { 
  const tx = await signer.sendTransaction({ to, value, data })
  return { hash: tx.hash }
}
const { claimUrl, transferId, txHash } = await claimLink.deposit({ sendTransaction })

For ERC20 (except USDC tokens), ERC721 and ERC1155 tokens before depositing, you need to approve tokens so that the contract has the opportunity to send them to the recipient

3. Re-generate Claim URL: Sender can generate a new claim URL (if the original claim URL is lost):

const { claimUrl, transferId } = await claimLink.generateClaimUrl({ signTypedData })
// share claimUrl with receiver

Retrieving claim link details

This methods help to retrieve claim link details by using deposit transaction hash (or sender & transferId).

As claim URL is never stored in database, it will be null on retrieval and new claim URL can be generated with claimLink.generateClaimUrl method call.

// fetch claim link using deposit transaction hash
const claimLink = await sdk.retrieveClaimLink({ chainId, txHash }) 

// or by using transferId
const claimLink = await sdk.retrieveClaimLink({ chainId, transferId })

Fetching claim links created by the sender

You can also fetch information about created links

const onlyActive = true // to get only active links (have not been redeemed or refunded yet) set parameter to true
const chainId = 80001
const sender = '0x2331bca1f2de4661ed88a30c99a7a9449aa84195'
const limit = 10 // parameter specifies the number of claim links in response. Not required. Default: 100
const offset = 10 // parameter is used to exclude from a response the first N claim links. Not required. Default: 0
const token = "0x0000000000000000000000000000000000000000" // the parameter defines claim links related to which token address should be found. Not required. By default, the search will be performed on all token addresses

const {
  claimLinks, // claim links fetched according to search parameters
  resultSet // information about fetched data (count, offset, total)
} = await sdk.getSenderHistory({
  // required params:
  chainId,
  sender,
  // optional params:
  onlyActive, // whether to only get the claim links that haven't been redeemed/refunded yet 
  limit,
  offset,
  token
})

Receiver methods

// claim link contains all needed info to render the claim page
const claimLink = await sdk.getClaimLink(claimUrl)

// const dest = "0x123..134" // ethereum address of the receiver
const txHash = await claimLink.redeem(dest)

You can also define version of the link using method getVersionFromClaimUrl

const version = sdk.getVersionFromClaimUrl(claimUrl)

Additionally you can use the getVersionFromEscrowContract method to determine the specific version of the link according to escrow contract

const escrowAddress = '0x0b962bbbf101941d0d0ec1041d01668dac36647a'
const version = sdk.getVersionFromEscrowContract(escrowAddress)

ClaimLink

Claim Link object contains methods and properties to facilitate both creation and redemption of the claim link.

ClaimLink.claimUrl is the URL shared with recipient. It is never stored in a remote database, so this property is going be null on retrieval. New claim URL can be generated with a claimLink.generateClaimUrl method call if needed.

ClaimLink properties:

transferId (string, transfer unique id, e.g. "1695985897077")
tokenType (string, token standard type, one of 'NATIVE' | 'ERC20' | 'ERC721' | 'ERC1155')
amount (string, atomic amount of tokens receiver going to claim, e.g. "1000000" for 1 USDC)
fee (string, atomic amount of tokens sender needs to pay as a fee, e.g. "100000" or 0.1 USDC)
expiration (string, unix timestamp after which the claim link will expire and amount will be sent back to sender unless it was claimed before)
totalAmount (string, total amount sender needs to deposit, amount + fee, e.g. "1100000" or 1.1 USDC)
token (string, token contract address, e.g. "0x2791bca1f2de4661ed88a30c99a7a9449aa84174")
chainId (number, network chain ID, e.g. 147 for Polygon network)
sender (string, Sender's Ethereum address, e.g. "0x2331bca1f2de4661ed88a30c99a7a9449aa84195")
escrow (string, Escrow contract address "0x1111bca1f2de4661ed88a30c44a7a9449aa84106")
version (string, claim link version, e.g. "1")
claimUrl (string, the URL that shall be shared with recipient, e.g. https://p2p.linkdrop.io/#/usdc?k=8uoxFBZtJZA72xHJzkdZnZoKbT15Swhn4f5z6jV8Q9U&s=JeGDRq7xAPRYhhYkXRJTXh1St97nRN2m2CQG27LzAnyEA4L4APm9GbDx6kDYEZYjmeGdJgyLpY1ap9FyPtogtG48r&i=mYfAE4p&c=137&v=1
status (string, claim link status, one of 'created' | 'depositing' | 'deposited' | 'redeemed'| 'redeeming' | 'error' | 'refunded' | 'refunding' | 'cancelled')
operations (array of operations related to the claim link)

operation:

type: (string, operation type, one of 'deposit' | 'redeem' | 'refund')
timestamp (unix timestamp when operation was made)
txHash: (string, ethereum transaction hash corresponding to the operation)
status: (string, operation status, one of 'pending' | 'completed' | 'error')
receiver: (string, Receiver's Ethereum address, present only for redeem operations, e.g. "0x2331bca1f2de4661ed88a30c99a7a9449aa84195")

Get Claim Link Status

In order to get the latest status of the claim link, use the following method:

const { status, operations } = await claimLink.getStatus()

Get Claim Link deposit params

In order to get params that will be passed to the sendTransaction method when making a deposit, you can use the public method getDepositParams

const {
  value,
  data,
  to,
} = claimLink.getDepositParams()

Error handling

Catching errors

try {
  ...
  const txHash = await claimLink.redeem('')
  ...
  
} catch (err) {
  console.log(err.message)
  // Validation Error: Argument "dest" is not provided (argument="dest", value="")

  console.log(err.error)
  // DESTINATION_ADDRESS_NOT_PROVIDED
}

Error types

SENDER_NOT_PROVIDED - argument "sender" is not provided to constructor
TOKEN_ID_NOT_PROVIDED - argument "tokenId" is not provided to constructor
AMOUNT_NOT_PROVIDED - argument "amount" is not provided to method or constructor
TOKEN_TYPE_NOT_PROVIDED - argument "tokenType" is not provided to constructor
TOKEN_NOT_PROVIDED - argument "token" is not provided to method or constructor
TRANSFER_ID_NOT_PROVIDED - argument "transferId" is not provided to constructor
SEND_TRANSACTION_NOT_PROVIDED - function "sendTransaction" is not provided to method
TOKEN_NOT_SUPPORTED_FOR_DEPOSIT_WITH_AUTH - current stablecoin is not supported
SIGN_TYPED_DATA_NOT_PROVIDED - function "signTypedData" is not provided to method
CANNOT_UPDATE_AMOUNT_FOR_ERC721 - you cannot specify the number of tokens for ERC721
MIN_LIMIT_FAILED - you cannot specify the number of tokens less than the lower limit
MAX_LIMIT_FAILED - you cannot specify the number of tokens greater than the upper limit
INVALID_DEPLOYMENT_PROPERTY - you cannot specify a deployment other than CBW or LD
BASE_URL_NOT_PROVIDED - argument "baseUrl" is not provided to constructor
GET_RANDOM_BYTES_NOT_PROVIDED - function "signTypedData" is not provided to constructor
CHAIN_ID_NOT_PROVIDED - argument "chainId" is not provided to constructor or method
CHAIN_NOT_SUPPORTED - current chain is not supported. Supported chains: 137, 11155111, 8453, 84531, 43114, 10, 42161, 100
FROM_NOT_PROVIDED - argument "from" is not provided to method
LIMITS_NOT_AVAILABLE_FOR_ERC721_AND_ERC1155 - limits are not available for ERC721 and ERC1155 tokens
DEPOSIT_STILL_PENDING - recipient attempts to claim tokens before the deposit transaction is completed