@terminal-packages/sdk

hex-sdk

This is Terminal's SDK. To install, do the following:

$ npm install @terminal-packages/sdk

Changelog

View changelog

Developer docs

View develop-docs

Contents

1. TerminalHttpProvider
   • web3
   • ethers
   • Injected window.ethereum from other 3rd party wallets
2. MetaMask
   • logging

TerminalHttpProvider

Hooking this custom provider up is super easy and once hooked up it will push all JSON-RPC calls to your logs in your Terminal account.

web3

https://www.npmjs.com/package/web3

Basic provider options

export enum SourceType {
  Terminal = 'Terminal',
  Truffle = 'Truffle',
  Alchemy = 'Alchemy',
  MetaMask = 'MetaMask'
}

JavaScript/TypeScript

import { TerminalHttpProvider, SourceType } from '@terminal-packages/sdk';
import Web3 from 'web3';

const web3 = new Web3(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal // source can be a dynamic string as well
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');

const web3 = new Web3(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal // source can be a dynamic string as well
  })
);

With web3 Provider Options

• timeout - optional
• headers - optional
• withCredentials - optional

JavaScript/TypeScript

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import Web3 from 'web3';

const web3 = new Web3(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');

const web3 = new Web3(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

With Your Own HTTP Provider

JavaScript/TypeScript

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import Web3 from 'web3';

const web3 = new Web3(
  new TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: new YourCustomHttpProvider()
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');

const web3 = new Web3(
  new sdk.TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: new YourCustomHttpProvider()
  })
);

Non-prod Environments

If you are a Terminal dev, you can run this against non-prod environments as well. The example below is with the basic provider options but environment can be passed in within any of the examples above:

Environment type enum:

export enum EnvironmentTypes {
  dev = 'dev',
  staging = 'staging',
  live = 'live'
}

JavaScript/TypeScript

import { TerminalHttpProvider, EnvironmentTypes } from '@terminal-packages/sdk';
import Web3 from 'web3';

const web3 = new Web3(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: 'node source',
    environment: EnvironmentTypes.dev
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');

const web3 = new Web3(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: 'node source',
    environment: sdk.EnvironmentTypes.dev
  })
);

ethers

https://www.npmjs.com/package/ethers

Basic Provider Options

export enum SourceType {
  Terminal = 'Terminal',
  Truffle = 'Truffle',
  Alchemy = 'Alchemy'
}

JavaScript/TypeScript

import { TerminalHttpProvider, SourceType } from '@terminal-packages/sdk';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal // source can be a dynamic string as well
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const ethers = require('ethers');

const provider = new ethers.providers.Web3Provider(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal // source can be a dynamic string as well
  })
);

With web3 provider options

• timeout - optional
• headers - optional
• withCredentials - optional

JavaScript/TypeScript

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const ethers = require('ethers');

const provider = new ethers.providers.Web3Provider(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

With Your Own HTTP Provider

JavaScript/TypeScript

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(
  new TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: new YourCustomHttpProvider()
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const ethers = require('ethers');

const provider = new ethers.providers.Web3Provider(
  new sdk.TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: new YourCustomHttpProvider()
  })
);

Non-prod Environments

If you are a Terminal dev, you can run this against non-prod environments as well. The example below is with the basic provider options but environment can be passed in within any of the examples above:

Environment type enum:

export enum EnvironmentTypes {
  dev = 'dev',
  staging = 'staging',
  live = 'live'
}

JavaScript/TypeScript

import { TerminalHttpProvider, EnvironmentTypes } from '@terminal-packages/sdk';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(
  new TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: 'node source',
    environment: EnvironmentTypes.dev
  })
);

Node

const sdk = require('@terminal-packages/sdk');
const ethers = require('ethers');

const provider = new ethers.providers.Web3Provider(
  new sdk.TerminalHttpProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: 'node source',
    environment: sdk.EnvironmentTypes.dev
  })
);

Injected window.ethereum from other 3rd party wallets

Please note that if you're using MetaMask please follow the guide here.

Our provider handle any injected custom provider in the window. If you're using a 3rd party wallet which injects the custom provider in the window.ethereum you can use that with our provider. All you have to do is pass in the window.ethereum into the customHttpProvider option within the TerminalHttpProvider class. Example below shows how you would do this:

Web3

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import Web3 from 'web3';

const web3 = new Web3(
  new TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: window.ethereum
  })
);

Ether

import { TerminalHttpProvider } from '@terminal-packages/sdk';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(
  new TerminalHttpProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    customHttpProvider: window.ethereum
  })
);

MetaMask

https://metamask.io/

Logging

If your dapp is using MetaMask as the wallet signer, you will not be able to use the custom provider code explained above in the TerminalHttpProvider section. MetaMask injects it's own web3 instance onto the global window of the browser (window.web3) and our script wraps that web3 instance with our TerminalHttpProvider so we can start logging jsonrpc calls for you. Don't worry, MetaMask will do all the calls still, we just proxy the request and the response so we can log it.

Please note that if you're only using the logging MetaMask feature, you do not need to install the sdk as well, you can literally drop the script below in your website and start logging.

To get all the amazing logging in your dapp, all you need to do is paste this script within the <head> tag of your website:

<!-- TERMINAL SCRIPTS -->
  <script src="https://storage.googleapis.com/terminal-sdk/metamask/latest/metamask-latest.min.js"></script>
  <script type="text/JavaScript">
      window.terminal.sdk.metamask.startLogging('YOUR_API_KEY');
  </script>
<!-- END TERMINAL SCRIPTS -->

By default it will use the live environment but if you want to use dev or staging you can use the 2nd parameter in the startLogging method:

dev:

window.terminal.sdk.metamask.startLogging('YOUR_API_KEY', 'dev');

staging:

window.terminal.sdk.metamask.startLogging('YOUR_API_KEY', 'staging');

If you want to use a fixed version of the MetaMask script you can. We deploy every version of the script to the CDN store against the same version as the sdk when that's deployed. You can hook in those fixed versions by replacing {{versionInfo}} with your version number you want to use.

<script src="https://storage.googleapis.com/terminal-sdk/metamask/{{versionNumber}}/metamask-{{versionNumber}}.min.js"></script>