README

Logo

@purefi/verifier-widget

Node.js module with the Verifier Widget for PureFI decentralized AML protocol. Providing widgets for communicating with PureFI issuers

Documentation

The package is built on top of @purefi/verifier-sdk

Widget API

PureFIWidget works around concept of signing messages and to do it properly it needs a signer.

So every time chain or user account changes, pass the new signer instance to PureFIWidget.setSigner()

// Example is based on ethers and metamask
import { ethers } from 'ethers';

const updateSigner = () => {
  const provider = new ethers.providers.Web3Provider(ethereum);
  const signer = provider.getSigner();
  PureFIWidget.setSigner(signer);
}

ethereum.on('accountsChanged', (accounts) => {
  // handling account changes
  updateSigner();
});

ethereum.on('chainChanged', (chainId) => {
  // handling chain changes
  updateSigner();
});

To render a widget into a DOM node, pass the element and relevant config to PureFIWidget.render()

import { PureFIWidget } from '@purefi/verifier-widget';

const element = document.querySelector('#widget');
const config = {
  address: {
    address: '0xaAaAAAAaaAAaaaAAAaaaaaAAAAAaaAaAaAAAAaaa',
    type: 'wallet',
  },
};

PureFIWidget.render(element, config);

In case you need more control over screening results, pass onSuccess and onError callbacks to PureFIWidget.render()

import { PureFIWidget } from '@purefi/verifier-widget';

const element = document.querySelector('#widget');
const config = {
  address: {
    address: '0xaAaAAAAaaAAaaaAAAaaaaaAAAAAaaAaAaAAAAaaa',
    type: 'wallet',
  },
};
const onSuccess = (response, thresholds) => console.log('onSuccess', response, thresholds);
const onError = (error) => console.log('onError', error);

PureFIWidget.render(element, config, onSuccess, onError);

Whenever widget container unmounts, you are supposed to notify PureFIWidget about it by passing the element to PureFIWidget.unmount()

// React example
const widgetContainerRef = useRef();

useEffect(() => {
  const widgetContainerElement = widgetContainerRef.current;
  PureFIWidget.render(
    widgetContainerElement,
    { shouldCheckSignerAddress: true, }
  );
  return () => {
    PureFIWidget.unmount(widgetContainerElement);
  };
}, []);

return (
  <div ref={widgetContainerRef}></div>
)

Widget Config

These are the available config options for a widget

{
  // 'address' to screen. If you ommit it, 'shouldCheckSignerAddress' will be forced to true
  address?: PureFIAddress;

  // 'riskThresholds' is used for evaluation
  // the status of wallet/contract from application perspective
  // Possible values are in range [0..100]. 'low' is supposed to be less than 'high' 
  riskThresholds?: {
    low?: number; // default is 25
    high?: number; // default is 75
  };

  // 'shouldFlushOnSignerChange' instructs PureFIWidget whether it should
  // or should not flush widget instance's state when signer changes 
  shouldFlushOnSignerChange?: boolean; // default is true

  // 'shouldShowNotice' option is responsible for showing or not showing
  // notice modal on every check
  shouldShowNotice?: boolean; // default is true

  // 'shouldCloseModalOnOverlayClick' option makes widget modals closable
  // on overlay click
  shouldCloseModalOnOverlayClick?: boolean; // default is true

  // 'shouldCheckSignerAddress' instructs PureFIWidget whether it should
  // or should not include signer address(user account) into screening
  shouldCheckSignerAddress?: boolean; // default is false

  // 'shouldShowUserRejectedError' defines to show or not to show
  // error message if a user cancels 'sign message' request
  shouldShowUserRejectedError?: boolean; // default is false

  // 'shouldShowMissingSignerError' defines to show or not to show
  // error message when signer is missing
  shouldShowMissingSignerError?: boolean; // default is true
  
  // 'i18n' can be used either to change or translate all the widget texts
  // feel free to import { DefaultI18n } from '@purefi/verifier-widget'
  // and check all the available options for replacing
  i18n?: PureFII18n;
}

Widget Styles

You are welcome to modify all the styles used by widget. Original styles can be found at

node_modules/@purefi/verifier-widget/lib/purefi-widget-example.css

We recommend that you copy them into your own app and modify to suit your needs

Demo

Codesanbox demo

Demo source code https://github.com/purefiprotocol/verifier-widget-demo

Usage no npm install needed!