@presend/verification

An npm package that provides an easy entry point to the presend.io Verification API. Using this SDK, you can verify a transaction using what we refer to as a VerificationPayload. If you have a Partner API key, you can use it instead of paying the fee to access the verification system.

Alternatively, the payload will first be used to calculate the appropriate fee required to use the Verification system. Once the user has paid the fee for a transaction, the payload will be sent over to the API, allowing one verification per payment, a fact which is also validated server-side. In addition to the verification process, this package provides utility functions to craft the VerificationPayload.

PresendVerificationSDK Class

Usage with Partner API Key

To use the SDK, instantiate the PresendVerificationSDK class with your Partner API Key.

import {
  PresendVerificationSDK,
  VerificationPayloadProps,
  SdkError,
  ProtocolError
} from '@presend/verification';

(async () => {
  const sdk = new PresendVerificationSDK({
    apiKey, // the partner API Key. required
    debug: true // prints debug logs. optional, defaults to false
  });

  const payload: VerificationPayloadProps = {
    sourceAddress: '0x...', // the address of the user sending the transaction. required
    targetAddress: '0x...', // the address of the user receiving the transaction. required
    targetChainIdHex: '0x1', // the chain id in hex format of the target network. required
    targetCryptoApi: 'kucoin', // the crypto api to be used for the transaction. required
    targetTokenAmount: 1, // the amount of the target token to be sent. required
    targetTokenAddress: '0x...', // the address of the target token. Use 'native' for the native token required
    targetTokenAmountDecimals: 8, // the decimals of the target token. optional, default to 18
    targetTokenSymbol: 'WBTC' // the symbol of the target token. required
  };

  try {
    const verificationResult = await sdk.verifyTransactionAsync({
      payload // the payload for the transaction to be verified. required
    });

    console.log(JSON.stringify(verificationResult));
  } catch (error: any) {
    // if not typescript, you can also check `error.name`
    if (error instanceof SdkError) {
      // SDK errors are errors that can are defined within the SDK and have associated context
      const { context } = error;
      // short description detailing what happened
      console.log(context.description);
      // enum giving presend dev team more detail where the error originated from
      console.log(context.component);

      if (error instanceof ProtocolError) {
        // Protocol Errors are more specific types of SdkErrors
        // These errors are mainly due to the Presend Verification protocol being mis-configured
      }

      if (error instanceof VerificationError) {
        // Protocol Errors are more specific types of SdkErrors
        // These errors are usually due to unexpected server-side errors
      }
    } else {
      // anything else here is completely unexpected
      // this can be anything from metamask errors to network errors
    }
  }
})();

Usage without Partner API Key

In order to use the SDK, you need to instanciate the PresendVerificationSDK class using an ethers signer object. The signer object is used to sign the VerificationPayload and to send the fee payment to the Verification contract.

import { ethers } from 'ethers';

import {
  PresendVerificationSDK,
  VerificationPayloadProps,
  SdkError,
  ProtocolError
} from '@presend/verification';

(async () => {
  // this example showcases a metamask signer,
  // but can be any ethers signer such as a private key signer
  const provider = new ethers.providers.Web3Provider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = provider.getSigner();

  const sdk = new PresendVerificationSDK({
    signer, // ethers signer object. required
    debug: true // prints debug logs. optional, defaults to false
  });

  const payload: VerificationPayloadProps = {
    sourceAddress: '0x...', // the address of the user sending the transaction. required
    targetAddress: '0x...', // the address of the user receiving the transaction. required
    targetChainIdHex: '0x1', // the chain id in hex format of the target network. required
    targetCryptoApi: 'kucoin', // the crypto api to be used for the transaction. required
    targetTokenAmount: 1, // the amount of the target token to be sent. required
    targetTokenAddress: '0x...', // the address of the target token. required
    targetTokenAmountDecimals: 8, // the decimals of the target token. optional, default to 18
    targetTokenSymbol: 'WBTC' // the symbol of the target token. required
  };

  try {
    const verificationResult = await sdk.verifyTransactionAsync({
      payload, // the payload for the transaction to be verified. required
      signer, // ethers signer object, overrides SDK signer. optional,
      skipPayment: false, // skip payment process. optional, defaults to false
      existingToken: undefined // existing payment token to be used. optional
    });

    console.log(JSON.stringify(verificationResult));
  } catch (error: any) {
    // if not typescript, you can also check `error.name`
    if (error instanceof SdkError) {
      // SDK errors are errors that can are defined within the SDK and have associated context
      const { context } = error;
      // short description detailing what happened
      console.log(context.description);
      // enum giving presend dev team more detail where the error originated from
      console.log(context.component);

      if (error instanceof ProtocolError) {
        // Protocol Errors are more specific types of SdkErrors
        // These errors are mainly due to the Presend Verification protocol being mis-configured
      }

      if (error instanceof VerificationError) {
        // Protocol Errors are more specific types of SdkErrors
        // These errors are usually due to unexpected server-side errors
      }
    } else {
      // anything else here is completely unexpected
      // this can be anything from metamask errors to network errors
    }
  }
})();

Result

{
  "verificationPassed": false,
  "message": "Transaction Verification Steps Failed"
}

Methods

verifyTransactionAsync method

Verify a transaction by obtaining an approved payment token and using it to authorize the transaction.

Parameters

• props: TransactionVerificationProps: The properties for verifying a transaction.
• props.payload: VerificationPayload: The payload for the transaction to be verified.
• props.skipPayment?: boolean: A flag indicating whether to skip the payment process.
• props.existingToken?: string: An existing payment token to be used for the transaction.

Returns

• Promise<VerificationResponse>: A promise that resolves with the result of the transaction verification.

resumeTransactionVerificationAsync method

Resume a transaction in pending or paid status.

Parameters

• transactionId: string: The id of the transaction to be resumed.

Returns

• Promise<VerificationResponse>: A promise that resolves with the result of the transaction verification.

getApprovedPaymentTokenAsync method

Obtain an approved payment token for a transaction.

Parameters

• props: ApprovedPaymentTokenProps: The properties for obtaining an approved payment token.
• props.payload: VerificationPayload: The payload for the transaction to be verified.

Returns

• Promise<string>: A promise that resolves with the approved payment token.

processPaymentAsync method

Process a payment for a transaction.

Parameters

• props: PaymentProcessProps: The properties for processing a payment.
• props.payload: VerificationPayload: The payload for the transaction to be verified.
• props.supportedNetwork: SupportedNetwork: The approved payment token for the transaction.

Returns

• Promise<void>: A promise that resolves when the payment has been processed.

getSupportedExchangesAsync method

Get the list of supported crypto apis used as the targetCryptoApi property within the verification payload.

Returns

• Promise<string[]>: A promise that resolves with the list of supported crypto apis.

getSupportedNetworksAsync method

Get the list of supported networks used as the targetChainIdHex property within the verification payload.

Returns

• Promise<SupportedNetwork[]>: A promise that resolves with the list of supported networks.

PricingUtility Class

A utility class used to fetch the pricing information for tokens by token address or by symbol pair. This uses the DexScreener API behind the scenes

Usage

import { PricingUtility } from '@presend/verification';

(async () => {
  const pricingUtility = new PricingUtility();

  const addrPrice = await pricingUtility.getPriceForTokenAddressAsync('0x...');
  console.log(addrPrice);

  const pairPrice = await pricingUtility.getPriceForPairAsync('USD WBTC');
  console.log(pairPrice);
})();

Methods

getPriceForTokenAddressAsync method

Get the price for a token by token address.

Parameters

• tokenAddress: string: The address of the token.
• tokenSymbol: string: The symbol of the token. Optional

Returns

• Promise<number>: A promise that resolves with the price in USD of the token.

getPriceForPairAsync method

Get the price for a token pair.

Parameters

• pair: string: The pair of the token. e.g. USD WBTC

Returns

• Promise<number>: A promise that resolves with the price in USD of the token pair.

TransactionUtility Class

A utility class used to fetch the historical Transactions for Presend Users.

Usage

import { TransactionUtility } from '@presend/verification';

(async () => {
  const transactionUtility = new TransactionUtility();

  const sourceTransactions = await transactionUtility.getTransactionHistoryBySourceAsync('0x...');
  console.log(sourceTransactions);

  const affilTransactions = await transactionUtility.getTransactionHistoryByAffiliateAsync('0x...');
  console.log(affilTransactions);

  const allTransactions = await transactionUtility.getAllTransactionHistoryAsync();
  console.log(allTransactions);
})();

Methods

getTransactionHistoryBySourceAsync method

Get the transactions for a source address.

Parameters

• sourceAddress: string: The source address of the transaction.

Returns

• Promise<Transaction[]>: A promise that resolves with the array of transactions.

getTransactionHistoryByAffiliateAsync method

Get the transactions for an affiliate address.

Parameters

• affiliateAddress: string: The affiliate address of the transaction.

Returns

• Promise<Transaction[]>: A promise that resolves with the array of transactions.

getAllTransactionHistoryAsync method

Get all the transactions.

Returns

• Promise<Transaction[]>: A promise that resolves with the array of transactions.