@terminal-packages/sdk

HexSDK - Ethereum Development Tools

Terminal is an developers platform for builing on Ethereum. Develop, test, and manage Ethereum artifacts and infrastructure in a unified workspace with Terminal. The Terminal toolkit provides developers with a broad range of utilities to construct robust and user-friendly decentralized applications or dapps.

HexSDK allows you to surface logs from arbitrary RPC endpoints and networks to your Terminal account. HexSDK is a simple drop-in wrapper around any Web3 provider with minimal configuration required on your part to get up and running.

• Drop in the Terminal subprovider to fetch logs for any RPC endpoint
• Surface logs for injected web3 providers
• Introduce cloud logging into your Truffle development environment
• Compatible with web3.js and ethers.js

To install, do the following:

npm:

$ npm install @terminal-packages/sdk

yarn:

$ yarn add @terminal-packages/sdk

TerminalHttpProvider Options

host: Any ethereum provider url of your choice
apiKey: An API key associated with your Terminal account
source: Any custom provider of your choice

Changelog

View changelog

Developer docs

View develop-docs

Contents

1. TerminalHttpProvider

   • web3
   • ethers
   • Injected window.ethereum from other 3rd party wallets who use http provider

2. TerminalWebsocketProvider

   • web3
   • ethers
   • Injected window.ethereum from other 3rd party wallets who use websocket provider

3. 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 http

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, 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
    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, SourceType } 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,
  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
    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: sdk.SourceType.Terminal, // source can be a dynamic string as well
    environment: sdk.EnvironmentTypes.dev
  })
);

ethers http

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

Basic provider options

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

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, 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
    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,
  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
    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: sdk.SourceType.Terminal, // source can be a dynamic string as well
    environment: sdk.EnvironmentTypes.dev
  })
);

Injected window.ethereum from other 3rd party wallets who use http provider

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, SourceType } 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, SourceType } 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
  })
);

TerminalWebsocketProvider

Due to the rewrite of web3 for 2.0 the code on web3 1 vs web3 2 is very different, this means we have to go down different paths of code depending on the version you use. We made this super easy for you to tell us in the examples below. By default if you do not supply it then it will default to 2.0. This is the main difference between the TerminalHttpProvider and TerminalWebsocketProvider interface and how you set it up. Please note if your on 1.0-beta version you do not need to supply the web3 version.

web3 websocket

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

Basic provider options

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

Please note if your on 1.0-beta then Web3Versions.two is the correct version if you ever want to supply the Web3Versions to a call.

export enum Web3Versions {
  one = '1',
  two = '2'
}

JavaScript/TypeScript

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

const web3 = new Web3(
  new TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
  })
);

Node

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

const web3 = new Web3(
  new sdk.TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
  })
);

With web3 provider options

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

JavaScript/TypeScript

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

const web3 = new Web3(
  new TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    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.TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

With your own websocket provider

JavaScript/TypeScript

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

const web3 = new Web3(
  new TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: new YourCustomWebsocketProvider()
  })
);

Node

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

const web3 = new Web3(
  new sdk.TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: new YourCustomWebsocketProvider()
  })
);

Ethers websocket

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

Basic provider options

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

Please note if your on 1.0-beta then Web3Versions.two is the correct version if you ever want to supply the Web3Versions to a call.

export enum Web3Versions {
  one = '1',
  two = '2'
}

JavaScript/TypeScript

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

const provider = new ethers.providers.Web3Provider(
  new TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
  })
);

Node

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

const provider = new ethers.providers.Web3Provider(
  new sdk.TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
  })
);

With web3 provider options

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

JavaScript/TypeScript

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

const web3 = new ethers.providers.Web3Provider(
  new TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

Node

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

const web3 = new ethers.providers.Web3Provider(
  new sdk.TerminalWebsocketProvider({
    host: 'https://yourethnodeurl.io',
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    timeout: 10000,
    headers: [{ name: 'x-custom-header' value: 'example' }],
    withCredentials: true
  })
);

With your own websocket provider

JavaScript/TypeScript

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

const web3 = new ethers.providers.Web3Provider(
  new TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: new YourCustomWebsocketProvider()
  })
);

Node

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

const web3 = new ethers.providers.Web3Provider(
  new sdk.TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: sdk.SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: new YourCustomWebsocketProvider()
  })
);

Injected window.ethereum from other 3rd party wallets who use websocket provider

Please note that if you're using MetaMask please follow the guide here and they only support http provider.

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 websocket provider. All you have to do is pass in the window.ethereum into the customWebsocketProvider option within the TerminalWebsocketProvider class. Please note your window.ethereum provider must support websockets for this to work. Example below shows how you would do this:

Web3

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

const web3 = new Web3(
  new TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: window.ethereum
  })
);

Ether

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

const provider = new ethers.providers.Web3Provider(
  new TerminalWebsocketProvider({
    apiKey: 'yourApiKey',
    source: SourceType.Terminal, // source can be a dynamic string as well
    web3Version: sdk.Web3Versions.one, // if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
    customWebsocketProvider: 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>