Token Negotiation

Token Negotiation is how a website discovers tokens it can use

Token Negotiation is the process by which Tokens and Websites negotiate to find the match.

For example, a travel booking website like booking.com might negotiate for the following tokens:

  • Travel agent's status token which allows special travel-agent booking.
  • Any airfare token which included free overnight stay for certain hotels.
  • Priority Guest Rewards tokens, which might allows free upgrades for certain hotels.
  • Any Payment Token that can be used to pay for the booking (e.g. American Express Explorer Credit).
  • COVID-19 attestation, which attests a recent negative test result or antibodies

If the browser supports TokenScript, it will handle the negotiation and provide the website with user's tokens to be used on this website. Otherwise, the website can ship bootstrap library to do the negotiation.

Negotiation Methods

TokenScript provides the following negotiation methods:

  1. TokenFilter based negotiation, which uses a filter to find a token.
  2. Capability based negotiation, by which a website provides an attestation signed by a token issuer's trust key, showing that the token is intended to be usable on that website;
  3. Expectation based negotiation, by which a token declares being able to do certain things (e.g. let the website receives 1ETH in payment).

These can be combined and mixed.

Negotiation Scope

The tokens that comes out of a negotiation on a web page is affected by 2 factors.

  1. The TokenScript provided by the web page. This can be done by adding the TokenScripts of possible outcomes in the HTML header section.
  2. The TokenScript provided by the user agent (wallet). This is affected by how many TokenScripts are cached on user's wallet.
  3. The "token.scope" meta tag (unimplemented).

Negotiation Process

Negotiation can be passive or active.

In a passive negotiation, the website declares the negotiation method and scope in HTML <meta> element, as seen in TokenNegotiationExamples. In a browser, the user is presented with a TokenBar. The user can click the tokens in the token bar any time to make that token "active" in the current session. It's possible for the user to not to choose anything in the entire session and the user is not forced to make a choice.

In an active negotiation, the website runs a JavaScript routine to do the negotiation. The user is presented with the choice of tokens and the user must make a choice or explicitly choose nothing. Such JavaScript routine can be hooked to a button, for example, "Sign-up for a newsletter" button might trigger the user to choose one of the tokens that can produce an email address proof.