Skip to content

Latest commit

 

History

History
371 lines (303 loc) · 15 KB

README.md

File metadata and controls

371 lines (303 loc) · 15 KB
Raw

Linkdrop SDK (V3)

Import and initialize SDK

import { LinkdropSDK } from 'linkdrop-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/v3
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 = LinkdropSDK({
  baseUrl,
  getRandomBytes,
  // apiKey,
  // apiUrl
})

Sender methods

Creating claim link

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

ERC20

const from = "0x2331bca1f2de4661ed88a30c99a7a9449aa84195" // Sender's Ethereum address
const token = "0x6f8a06447ff6fcf75d803135a7de15ce88c1d4ec" // token contract address
const tokenType = "ERC20"
const chainId = 137 // network chain ID
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 amount = "1000000" // atomic amount of tokens that sender wants to send (before fees)

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

ERC721

const from = "0x2331bca1f2de4661ed88a30c99a7a9449aa84195" // Sender's Ethereum address
const token = "0x2b7ca50f95e830cd7f47f42f156a6934906e3957" // token contract address
const tokenType = "ERC721"
const chainId = 137 // network chain ID
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 = '4'

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

ERC1155

const from = "0x2331bca1f2de4661ed88a30c99a7a9449aa84195" // Sender's Ethereum address
const token = "0x344ed1c4387f7f18de4655a982513e22a8034bd3" // token contract address
const tokenType = "ERC1155"
const chainId = 137 // network chain ID
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"
const amount = "1"

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

You can update an 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 = "0x6f8a06447ff6fcf75d803135a7de15ce88c1d4ec" // token contract address. Not required if tokenType is NATIVE
const tokenType = "ERC20" // one of "NATIVE" | "ERC20" | "ERC721" | "ERC1155"
const chainId = 137 // network chain ID

const {
  minTransferAmount,
  maxTransferAmount,
  minTransferAmountUSD,
  maxTransferAmountUSD
} = 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)


// authConfig is optional. Use it if you need to define domain and method of authorization
const authConfig = {
  domain: { 
    // required params
    name,
    version,
    verifyingContract,

    // optional params
    chainId,
    salt
  },
  authorizationMethod // "ApproveWithAuthorization" || "ReceiveWithAuthorization"
}

const { claimUrl, transferId, txHash } = await claimLink.depositWithAuthorization({
  signTypedData,
  authConfig
})

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 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 = 137
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

ClaimLink object contains methods and properties to facilitate both creation and redemption of the claim link. ClaimLink class has been updated over different versions of the library. Specifically, there are multiple versions of ClaimLink with different features:

  • Version 3.11 (ClaimLinkV3_11)
  • Version 3.14 (latest)

To handle the different versions of ClaimLink, the retrieveClaimLink method of the SDK can return an instance of ClaimLink from any of the supported versions.

import { ClaimLink, ClaimLinkV3_11 } from 'linkdrop-sdk';
const claimLink = await sdk.retrieveClaimLink({
  ...
});

// Check if the ClaimLink instance is from the latest version (3.14) and can call an appropriate method
if (claimLink instanceof ClaimLink) {
  // call methods for the latest version of Linkdrop SDK ClaimLink
} else if (claimLink instanceof ClaimLinkV3_11) {
  // call methods for version 3.11 of Linkdrop SDK ClaimLink
}

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")- - pendingTxs (number) how many Linkdrop transactions there are that are stuck in the mempool
  • pendingTxSubmittedBn (number) block number when the transaction was submitted for the inclusion into blockchain
  • pendingTxSubmittedAt (number) UNIX timestamp when the oldest pending transaction was submitted for the inclusion into blockchain
  • pendingBlocks (number) how many blocks the oldest pending transaction has been stuck in the mempool.
  • 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)
  • encryptedSenderMessage (string)
  • senderMessage (string)
  • 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()

Add message (method is available only for link creator)

You can add message before the deposit. The method will be locked after the deposit

const claimLink = await sdk.createClaimLink({
  ...
})

const message = 'Hello world!'
const signTypedData = (domain, types, message) => signer.signTypedData(domain, types, message)

await claimLink.addMessage({
  message, // max length of message is 140
  signTypedData,

  // optional params. By default is set to 12. Can be modified to any number between 6 and 43
  encryptionKeyLength: 12 
})

Decrypt message (method is available only for link creator if retrieved ClaimLink is version 3.14 or higher)

import { ClaimLink } from 'linkdrop-sdk';

const claimLink = await sdk.retrieveClaimLink({
  ...
})

if (claimLink && claimLink instanceof ClaimLink) {
  const signTypedData = (domain, types, message) => signer.signTypedData(domain, types, message)

  const decryptedMessage = await claimLink.decryptSenderMessage({
    signTypedData
  })

  console.log(decryptedMessage) // 'Hello world!'
}

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
  • CANNOT_UPDATE_AMOUNT_FOR_ERC721 - you cannot specify the number of tokens for ERC721
  • LIMITS_NOT_AVAILABLE_FOR_ERC721_AND_ERC1155 - limits are not available for ERC721 and ERC1155 tokens
  • 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
  • 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
  • DEPOSIT_STILL_PENDING - recipient attempts to claim tokens before the deposit transaction is completed