@alphawallet/token-negotiator

token-negotiator

The token-negotiator is an NPM package designed for use with TokenScript.

TokenScript is a framework which improves functionality, security and usability of blockchain token. It creates a layer between a blockchain and user devices, adding information, rules and functionalites both onchain and offchain.

For more information please visit: https://tokenscript.org/.

Examples

https://tokenscript.github.io/token-negotiator-examples/

Documentation

guides and deployment NPM

Usage

npm i @alphawallet/token-negotiator

import { Negotiator } from '@alphawallet/token-negotiator';

Negotiator

Creates a new instance of the Negotiator module.

  /**
  *
  * @param {Object} filter optional filter rules 
  * @param {Object} options api options (required options shown below)
  * @param {String} tokenName name (required)
  */
  const negotiator = new window.Negotiator({
    filter: { 'devconId': 6 },
    tokenName: "devcon-ticket",
    options: { userPermissionRequired: true }
  });

Resolves the tokens with filter applied.

  /**
  *
  * @returns {object} token data { success: true/false, tokens: [...{}] }
  */
  const negotiatedTokens = await negotiator.negotiate();

Authenticate ownership of Token.

  /**
  * @param {URL} unEndPoint end point must return { un: number, expiry: date }
  * @param {object} unsignedToken selected un-signed token/ticket
  * @returns {object} { status (true/false), useToken (object), useEthKey (object)
  * - useTicket and ethKey can be used to verify a ticket is valid. 
  * - status indicates if the function was successful.
  */
  const { status, useToken, useEthKey } = await negotiator.authenticate({ unEndPoint, unsignedToken });

Filters

When loading a page you may wish to only show a select set of tokens.

For example: with the following key/values devconId, ticketId, ticketClass you may wish to only show devconId when the value is 6 and of ticketClasses of A. Below is an example of how this can be applied.

  const negotiator = new window.Negotiator({
    filter: { devconId: 6, ticketClass: "A" },
    tokenName: "devcon-ticket",
    options: {}
  });

Negotiator Options

userPermissionRequired - Default is false. When true, the Token Negotiator will not allow negotiate() to be used until access is given. This feature can be thought of in a similar way to how cookies are managed with end user permissions.

Example Use below:

  // token list
  let tokens = [];
  // initial config object
  const negotiator = new window.Negotiator({
    filter: { 'devconId': 6 },
    tokenName: "devcon-ticket",
    options: { userPermissionRequired: true }
  });
  // An example click event where the User clicks 'Yes' or 'No' to allow access.
  const userPermissionClickEvent = (bool) => {
    // set permission inside negotiator state
    negotiator.setUserPermission(bool);
    // if the user has selected to give access
    if(negotiator.getUserPermission() === true){
      // get the tokens and utilise them in the web application
      negotiator.negotiate().then(result => {
        tokens = result.tokens;
      });
    }
  }

User consent to connect the website to the token, this is only required when 'userPermissionRequired' is set as true.

  /**
  * @param {Boolean} boolean 
  */
  negotiator.setUserPermission(boolean);

The Negotiator will hold state of the permission, which can be accessed at any time.

  /**
  * @returns {Boolean} boolean
  */
  negotiator.getUserPermission();