TLSN Provider API

This page is a reference for the TLSN Extension's Provider API. TLSN Extension injects the provider API into websites visited by its users using the window.tlsn provider object.

Connect to TLSN Extension

tlsn.connect()

This method is used to request a website to be connected to the extension. Once a provider is connected, a website can use the provider API to suggest actions to the extension.

Parameters

None.

Returns

A promise that resolves to the full provider API object.

Example

const client = await tlsn.connect();

Screenshot

Provider API Method

client.getHistory(method, url, metadata)

This method is used to request proof history from the extension.

Parameters

1. method: a glob pattern matching request method of the proof. (e.g. get, {get,post}, *)
2. url: a pattern matching request url of the proof. (e.g. **, https://swapi.dev/**)
3. metadata: an object containing glob patterns of matching metadata about the request. (e.g. {id: "swapi-proof-1"})

Returns

A promise that resolves to an array of proof header data.

type ProofHeader = {
  id: string;
  method: string;
  notaryUrl: string;
  time: string;
  url: string;
  websocketProxyUrl: string;
}

Example

const proofs = await client.getHistory('*', '**', {id: '0x1234567890'});

Screenshot

client.getProof(id)

This method is used to request full data of a specific proof id.

Parameters

1. id: id of a proof

Returns

A promise that resolves to the proof data or null.

type ProofData = {
  notaryUrl: string;
  session: Session; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
  substrings: Substrings; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
}

Example

const proof = await client.getProof('FE512M1.72007336176400000000000000000000');

Screenshot

client.notarize(url, requestOptions, proofConfig)

This method is used to request notarization of a request.

Parameters

1. url: url of the request
2. requestOptions: An object containing the following:
   1. method: GET, POST, PUT, etc
   2. headers: a map of headers
   3. body: string content of the request body
3. proofConfig: An object containing the following:
   1. notaryUrl: url of the notary (default to the extension setting)
   2. websocketProxyUrl: url of the websocket proxy (default to extension setting)
   3. maxSentData: Max Sent Data allowed (default to extension setting)
   4. maxRecvData Max Recv Data allowed (default to extension setting)
   5. maxTranscriptSize: Max transcript size allowed (default to extension setting)
   6. metadata: a object of metadata

Returns

A promise that resolves to the proof data.

type ProofData = {
  notaryUrl: string;
  session: Session; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
  substrings: Substrings; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
}

Example

const proof = await client.notarize(
  'https://swapi.dev/api/planets/9',
  {
    method: 'get',
    headers: {
      "Accept": "application/json",
      "Accept-Encoding": "identity",
      "Connection": "close",
      "Cookie": "csrftoken=blahblahblah",
    }
  },
  {
    metadata: {id: 'test-1'},
  }
);

Screenshot

client.installPlugin(url, metadata)

This method is used to request installation of a plugin.

Parameters

1. url: url to the plugin wasm file
2. metadata: a object of metadata about the plugin

Returns

A promise that resolves to plugin id.

Example

const pluginId = await client.installPlugin(
  'https:/tlsnotary/tlsn-extension/raw/main/plugins/twitter_profile/index.wasm',
  { id: 'demo-plugin-1' }
);

Screenshot

client.getPlugins(url, origin, metadata)

This method is used to request installation of a plugin.

Parameters

1. url: a glob pattern matching url to the plugin wasm file
2. origin: a glob pattern matching origin that request installation of the plugin
3. metadata: a object of glob patterns matching metadata about the plugin

Returns

A promise that resolves to plugin config.

type PluginConfig = {
  hash: string;
  title: string;
  description: string;
  icon?: string;
  steps?: StepConfig[];
  hostFunctions?: string[];
  cookies?: string[];
  headers?: string[];
  requests: { method: string; url: string }[];
  notaryUrls?: string[];
  proxyUrls?: string[];
};

Example

const plugin = await client.getPlugins('**', 'https://swapi.dev', {id: 'demo-plugin-1'});

Screenshot

client.runPlugin(id)

This method is used to request execution of a plugin.

Parameters

1. id: id of a plugin

Returns

A promise that resolves to the proof data.

type ProofData = {
  notaryUrl: string;
  session: Session; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L7-L11;
  substrings: Substrings; // https:/tlsnotary/tlsn-js/blob/main/src/types.ts#L73-L76
}

Example

const plugin = await client.runPlugin("6931d2ad63340d3a1fb1a5c1e3f4454c5a518164d6de5ad272e744832355ee02");

Screenshot