# Introduction

## :book: Version: @polymathnetwork/sdk - v3.0.0

## :thinking: Purpose

The Polymath SDK's main goal is to provide external developers a set of tools to build powerful applications that interact with the Polymath protocol. It focuses on abstracting away the complexities of smart contracts (and the blockchain itself) and expose a simple but complete interface. The result is a feature-rich, user-friendly Node.js library.

## :hammer\_pick: Setup your Project

The SDK works equally well on browsers and Node.js applications. For simplicity, we're going to setup a Node.js project. Any steps specific to browser environments will be highlighted.

First, create a new Node.js project:

```bash
mkdir sdk-demo && cd sdk-demo
npm init
```

Follow the `npm init` wizard to initialize your project. Then, install the SDK, which is the only dependency we need to build a simple application.

```bash
npm add @polymathnetwork/sdk@2.0.1-beta.24
```

Finally, add an entry js file such as `index.js`, which imports the SDK API as well as some browser utils that we're going to use later.

```typescript
import { Polymath, browserUtils } from '@polymathnetwork/sdk';
```

### :ox: Instantiate and Initialize the Polymath client

Before we use the Polymath SDK, we need to connect to the deployed smart contracts on the desired Ethereum network.

```typescript
const privateKey = process.env.PRIVATE_KEY;
const networkId = 1; // Or you can detect the current network in browser environments via browserUtils.getNetworkId()
const networkConfigs = {
    1: {
        polymathRegistryAddress: '0xdfabf3e4793cd30affb47ab6fa4cf4eef26bbc27',
        providerUrl: 'https://mainnet.infura.io/v3/[INFURA_PRODUCT_ID]',
        privateKey
    },
    42: {
        polymathRegistryAddress: '0x5b215a7d39ee305ad28da29bf2f0425c6c2a00b3',
        providerUrl: 'https://kovan.infura.io/v3/[INFURA_PRODUCT_ID]',
        privateKey
    },
};
const config = networkConfigs[networkId];
const polyClient = new Polymath();
await polyClient.connect(config);
```

`PolyClient.connect()` accepts three parameters:

* `polymathRegistryAddress` is the address of the main registry that keeps track of core components of the system, including the addresses of other registries.
* `httpProviderUrl` is an URL pointing to an Ethereum node that enables you to view and interact with the blockchain, via HTTP. Said node can be a local `geth` or `parity` node, or a 3rd-party provider such as `Infura`.
* `privateKey` is the private key used to sign transactions sent from the SDK.

**On browsers**, some plugins such as Metamask automatically inject a Web3 instance onto the browser for your webpage to use. If using such plugins, you can omit passing `httpProviderUrl` and `privateKey`. The SDK will use the injected provider behind the scenes.

You may detect the currently selected network using `browserUtils.getNetworkId()`, which returns the network's ID (e.g., 1 for mainnet).

## :flag\_white: Prerequisites

#### Familiarity with Polymath smart contracts

Make sure you understand the purpose of the ST-20/ERC-1400 standard. Polymath's Smart Contract [Github repo](https://github.com/PolymathNetwork/polymath-core/) is a great resource to get started.

#### Familiarity with React and Redux

The tutorial applications referenced throughout Polymath's SDK documentation are composed of pure React components and use React hooks to manage state.

#### Metamask Browser Plugin

Using a dApp requires an Ethereum account/wallet to sign transactions and pay for fees. Metamask is a browser wallet that also exposes a provider connected to an Ethereum node so you don't have to run your own.

* Make sure to install [Metamask](https://metamask.io/) on a browser.
* Follow initialization steps in order to create your account.
* In these tutorial applications, we're going to interact with Polymath's smart contracts on the Kovan test network. Make sure to obtain some Kovan ETH (KETH) beforehand. 1 KETH should be sufficient.

#### Obtaining POLY

POLY is an ERC20 token required to conduct certain paid operations on the Polymath network. For example, reserving a token symbol or attaching additional modules to your security token requires a predetermined amount of POLY. The manner in which POLY tokens are obtained varies depending on the Ethereum network in use.

* Kovan: you can obtain Kovan POLY, for free, from the deployed [`PolyTokenFaucet` contract](https://github.com/PolymathNetwork/polymath-core/#v200-1). The SDK will obtain POLY from the faucet on Kovan (or local testnets) whenever it's needed for certain SDK functions (e.g. symbol reservation).
* Mainnet: you can buy POLY tokens on Mainnet using one of [these markets](https://coinmarketcap.com/currencies/polymath-network/#markets).

## :man\_teacher: Tutorials

The Polymath SDK documentation is segmented into tutorials to help you understand how to use the SDK to create, manage, and distribute your security tokens. 

Each tutorial features a standalone application that showcases a specific set of functionalities that the SDK provides. You can find documentation on how each tutorial was built on its Github page. This documentation will focus solely on the components interacting with the SDK. 

We recommend visiting Github and launching each tutorial application while working through the documentation.