Getting Started with TerminalSDK

Surface logs from any environment to your Terminal account for a seamless debugging and analytics experience.

The TerminalSDK provides access to an assortment of different tools allowing you to surface all logs and other relevant data to your Terminal account in a variety of different ways. Our SDK offers the following interfaces:

  • TerminalHttpProvider - This is the most popular. Used for web3 providers and network endpoints more details below.

  • TerminalWebsocketProvider - This is used for surfacing logs from websocket providers.

  • TerminalIpfsClient - An IPFS client with support for all of the methods available in the Infura IPFS API.

  • TerminalApolloLink - Used for surfacing logs from subgraphs.

Because not all sources follow a standard interface we also offer a few custom interfaces designed for specific sources such as a 0x-mesh node or WalletConnect.

Installing TerminalSDK

In order to use TerminalSDK in your dapp, you'll need to have web3.js installed as well as generate an API key from your profile page. To install web3.js run one of the following commands:

yarn add web3

npm install web3

Now you'll need to install TerminalSDK from npm. To do so, run one of the following commands:

yarn add @terminal-packages/sdk

npm install @terminal-packages/sdk

All of the documentation can be found as well on our npm page here.

TerminalHttpProvider

The TerminalHttpProvider allows you to surface logs from arbitrary RPC endpoints and networks to your Terminal account. The TerminalHttpProvider is a simple drop-in wrapper that can be used on any web3 provider with minimal configuration required on your part . In this section of the docs we will walk through the necessary steps to get up and running with TerminalSDK.

Logs pushed to your Terminal account can also be viewed from your command line using TerminalCLI.

The following is a general method using the TerminalHttpProvider. For instructions on integrating a specific wallet or infrastructure provider check out the integrations tab in the docs or on our website. Here you can find an array of different web3 providers and wallets along with how to integrate them. Our SDK supports any web3 provider that uses the standard HTTP provider interface even if we dont have it specifically listed. If you are trying to integrate TerminalSDK and run in to any issues, please feel free to reach out.

TerminalHttpProvider Options

  1. host: The Ethereum provider URL of your choice.

  2. customHttpProvider: a custom Ethereum provider of your choice.

  3. apiKey: An API key associated with your Terminal account.

  4. source: A name for your custom provider. Used to filter Terminal logs.

  5. projectId: The Id for the Terminal project associated with the provider endpoint you are logging.

  6. web3Version: the version of web3 your are using. only required if using web3 1.x

  7. networkSource: is a string. This is not required, however allows you to set the network you are using for better logs. (ie. using portis to interact with a skale side chain)

Your projectId can be found in the project settings under the info section. You should use EITHER host or customHttpProvider, not both. If you are logging from an external RPC endpoint then you should use host instead of customHttpProvider.

The source option can be filled out using one of the sources from the enum SourceType or just a string if it is not defined in the enum. Below are the available options in the enum.

export enum SourceType {
Terminal = 'Terminal',
Truffle = 'Truffle',
Alchemy = 'Alchemy',
MetaMask = 'MetaMask',
Infura = 'Infura',
Pocket = 'Pocket',
Ledger = 'Ledger',
Web3ProviderEngine = 'Web3ProviderEngine',
WalletLink = 'WalletLink',
TruffleHDWalletProvider = 'TruffleHDWalletProvider',
Portis = 'Portis'
}

Due to the rewrite of web3 for 2.0 the code on web3 1.x vs web3 2.x 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. Please note if your on 1.0-beta version you do not need to supply the web3 version.

Once TerminalSDK is installed, simply wrap your web3 provider with TerminalHttpProvider. You will need an Ethereum client provider, whether from Terminal, infura, or another endpoint provider.

Web3.js Custom Provider Setup

If you are using a custom web3 provider like Pocket, HD wallet provider and many others, then you will be using the customHttpProvider option as opposed to host

In your Javascript project, wherever you initialize your Web3 provider, it probably looks something like the following:

App.js
import Web3 from 'web3';
const provider = new Web3.providers.HttpProvider("YOUR_ENDPOINT_URL")
const web3 = new Web3(provider);

Here we are initializing our web3 object with a custom version of HttpProvider as the provider. To initialize this same endpoint with Terminal as your subprovider, simply change the web3 initialization step to the following code. If you initialize multiple instances of web3 in your application, then you should wrap each instance with the SDK at initialization.

Javascript/Typescript
import { TerminalHttpProvider, SourceType, Web3Versions } from '@terminal-packages/sdk';
import Web3 from 'web3';
const web3 = new Web3(
new TerminalHttpProvider({
apiKey: 'yourApiKey',
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be any static or dynamic string as well
source: SourceType.Terminal,
customHttpProvider: new YourCustomHttpProvider()
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: Web3Versions.one,
})
);

This can be done in Node as well as Javascript/Typescript as follows:

Node
const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');
const web3 = new Web3(
new sdk.TerminalHttpProvider({
apiKey: 'yourApiKey',
// projectId is not required to log but we suggest
// using it for the best experience
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be a dynamic string as well
source: sdk.SourceType.Terminal,
customHttpProvider: new YourCustomHttpProvider()
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: sdk.Web3Versions.one
})
);

Once you have wrapped your dapp's network provider, logs will begin surfacing to your Terminal Account immediately. After a few calls have been made it will probably look something like this:

Ethers.js Custom Provider Setup

TerminalSDK is also compatible with ethers.js. Initializing ethers.js with the Terminal subprovider is a very similar process to that of Web3.js. To do so, pass in the following logic to your application:

Javascript/TypeScript
import { TerminalHttpProvider, SourceType, Web3Versions } from '@terminal-packages/sdk';
import { ethers } from 'ethers';
const provider = new ethers.providers.Web3Provider(
new TerminalHttpProvider({
apiKey: 'yourApiKey',
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be any static or dynamic string as well
source: SourceType.Terminal,
customHttpProvider: new YourCustomHttpProvider(),
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: Web3Versions.one,
})
);

Or if your using Node as opposed to Javascript/Typescript:

Node
const sdk = require('@terminal-packages/sdk');
const ethers = require('ethers');
const provider = new ethers.providers.Web3Provider(
new sdk.TerminalHttpProvider({
apiKey: 'yourApiKey',
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be a dynamic string as well
source: sdk.SourceType.Terminal,
customHttpProvider: new YourCustomHttpProvider(),
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: sdk.Web3Versions.one
})
);

External RPC Endpoints

If your program simply uses a static RPC endpoint to make web3 calls such as an Infura endpoint, then your web3 instance is likely initialized in this way:

import Web3 from 'web3';
const web3 = new Web3("YOUR_RPC_ENDPOINT");

For static RPC endpoints, the host option will be used instead of customHttpProvider. This is the primary difference in terms of surfacing logs. Wrapping your RPC endpoint will look something like this:

Javascript/Typescript
import { TerminalHttpProvider, SourceType, Web3Versions } from '@terminal-packages/sdk';
import Web3 from 'web3';
const web3 = new Web3(
new TerminalHttpProvider({
host: 'https://yourethnodeurl.io',
apiKey: 'yourApiKey',
// projectId is not required to log but we suggest
// using it for the best experience
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be a dynamic string as well
source: SourceType.Terminal
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: Web3Versions.one,
})
);

If you are using Node, then wrapping the TerminalSDK will look like this:

NODE
const sdk = require('@terminal-packages/sdk');
const Web3 = require('web3');
const web3 = new Web3(
new sdk.TerminalHttpProvider({
host: 'https://yourethnodeurl.io',
apiKey: 'yourApiKey',
// projectId is not required to log but we suggest
// using it for the best experience
projectId: 'YOUR_TERMINAL_PROJECT_ID',
// source can be a dynamic string as well
source: sdk.SourceType.Terminal
// if your using web3 1 (NONE BETA) please tell us, if you're not please delete this property
web3Version: sdk.Web3Versions.one,
})
);