<p align="center">
<img src="https://raw.githubusercontent.com/NibiruChain/ts-sdk/develop/img/nibijs.png" width="100%">
</p>

<!-- NOTE: Use direct links for external sites that copy these files. -->

<p align="center">
The official TypeScript SDK for the Nibiru blockchain!
</p>

<div style="display: flex; flex-direction: row; gap: 4px;">
<!-- Badge | NPM version -->
<a target="_blank" href="https://www.npmjs.com/package/@nibiruchain/nibijs">
  <img src="https://img.shields.io/npm/v/@nibiruchain/nibijs.svg?color=AE8CCD" style="height: 20px">
</a>

<!-- Badge | Test workflows -->
<a target="_blank" href="https://github.com/NibiruChain/ts-sdk/actions/workflows/test-ts-sdk.yaml" alt="⛓️ Tests @nibiruchain/nibijs">
  <img src="https://github.com/NibiruChain/ts-sdk/actions/workflows/test-ts-sdk.yaml/badge.svg?branch=main" style="height: 20px">
</a>

<!-- Badge | NPM downloads -->
<a target="_blank" href="https://www.npmjs.com/package/@nibiruchain/nibijs">
  <img src="https://img.shields.io/npm/dm/@nibiruchain/nibijs.svg?color=FFF3CD" style="height: 20px">
</a>

<!-- Badge | NPM license -->
<a target="_blank" href="https://github.com/NibiruChain/ts-sdk/blob/main/LICENSE">
  <img src="https://img.shields.io/npm/l/express.svg?color=050505" style="height: 20px">
</a>

<!-- Badge | Discord members -->
<a target="_blank" href="https://discord.gg/nibirufi">
  <img src="https://dcbadge.vercel.app/api/server/nibirufi?style=flat" style="height: 20px">
</a>
</div>

The NibiJS (`@nibiruchain/nibijs`) package makes it possible to interact with Nibiru from a Node.js or browser environment. `nibijs` provides simple abstractions for core data structures, serialization, key management, API requests, and the submission of transactions.

The `nibijs` source code can be found in the `src` directory.

#### Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Example: Creating a wallet](#example-creating-a-wallet)
  - [Example: Querying](#example-querying)
  - [Indexer queries](#indexer-queries)
  - [Example: Sending funds](#example-sending-funds)
- [Codebase structure](#codebase-structure)
- [Development Quick Start](#development-quick-start)
- [🔓 License](#-license)

To learn more about Nibiru, see [nibiru.fi/docs](https://nibiru.fi/docs)

---

## Installation

[@nibiruchain/nibijs][npm-nibijs] is available on the npm registry.

[npm-nibijs]: https://www.npmjs.com/package/@nibiruchain/nibijs

```
npm install @nibiruchain/nibijs # or yarn add
```

## Usage

`NibiruQuerier` reads chain state and `NibiruTxClient` signs and broadcasts transactions. `HeartMonitor` reads the indexer. Wallets come from `newRandomWallet` and `newSignerFromMnemonic`.

### Example: Creating a wallet

```js
import { newRandomWallet } from "@nibiruchain/nibijs"

// Create a new Nibiru wallet
const wallet = await newRandomWallet()
const [{ address }] = await wallet.getAccounts()

// Save the mnemonic somewhere to re-use the account
console.log("mnemonic: ", wallet.mnemonic)
console.log("address: ", address)
```

### Example: Querying

```js
import { NibiruQuerier, Testnet } from "@nibiruchain/nibijs"

export const CHAIN = Testnet(2)
const querier = await NibiruQuerier.connect(CHAIN.endptTm)

// Query balances
const exampleAddress = "nibi17dz4cdw5fmm2cxd4ht9xvjmpw3ycmpkpcc6js9"
const balances = await querier.getAllBalances(exampleAddress)
console.log("balances: %o", balances)

// Query the latest block. Pass a height to getBlock when the node still has that block.
const block = await querier.getBlock()
console.log("block: %o", block)
```

### Indexer queries

Heart Monitor examples for balances, transaction history, IBC transfers, staking, and oracle prices are in [QUERIES.md](https://github.com/NibiruChain/ts-sdk/blob/main/QUERIES.md).

### Example: Sending funds

```js
import {
  NibiruTxClient,
  newSignerFromMnemonic,
  Testnet,
  NibiruQuerier,
} from "@nibiruchain/nibijs"
import { coins } from "@cosmjs/proto-signing"

export const CHAIN = Testnet(2)
const mnemonic = "your mnemonic here..."
const signer = await newSignerFromMnemonic(mnemonic)
const querier = await NibiruQuerier.connect(CHAIN.endptTm)
const txClient = await NibiruTxClient.connectWithSigner(CHAIN.endptTm, signer)
const [{ address: fromAddr }] = await signer.getAccounts()

// Check balance before sending tokens
const exampleAddress = "nibi1mzjkw9z5ugajxchl884y0c28lk2627hpuljuw4"
let balances = await querier.getAllBalances(exampleAddress)
console.log("balances: %o", balances)

const tokens = coins(5, "unibi")
// "auto" simulates gas and multiplies it by 1.4. The client prices that gas at 0.025unibi.
// A number here is that multiplier, not a fee in unibi.
const txResp = await txClient.sendTokens(
  fromAddr,
  exampleAddress,
  tokens,
  "auto"
)
console.log(txResp)

// sendTokens resolves after the transaction is included in a block.
balances = await querier.getAllBalances(exampleAddress)
console.log("balances: %o", balances)
```

## Codebase structure

| Directories of `@nibiruchain/nibijs` | Purpose/Utility                                                                                                                          |
| :----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `common`                             | home to several commonly needed types, constants and configurations such as Network.                                                     |
| `msg`                                | Implements functions for creating messages (`Msg`s). These are objects that trigger state-transitions and get wrapped into transactions. |
| `query`                              | For querying state via the consensus engine of a full-node and the application blockchain interface (ABCI).                              |
| `tx`                                 | For signing and to submitting transactions given a set of `Msg` objects.                                                                 |
| `wallet`                             | A simple wrapper around the Keplr wallet. This module will grow as support is added for other wallets (like MetaMask).                   |

`@nibiruchain/protojs` provides types generated from the protocol buffers of the Cosmos-SDK, Tendermint Core, and Nibiru Chain. For most use cases, it won't be necessary to interact with this layer.

---

<!-- TODO: ## 📜 Contribution Guidelines -->

## Development Quick Start

1. Install and use `nvm`.

   ```bash
   wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.6/install.sh | bash
   nvm use
   ```

2. Install yarn.

   ```sh
   npm install -g yarn
   ```

3. Then, install package dependencies. At the root of the repository, run

   ```sh
   yarn
   ```

4. Initialize git submodules

   ```sh
   git submodule init
   git submodule update
   ```

5. Lastly, compile the code in each package.

   ```sh
   yarn build
   ```

See [HACKING.md](https://github.com/NibiruChain/ts-sdk/blob/main/HACKING.md) for the full development guide. It includes instructions on:

1. Running tests
2. Generating code for the @nibiruchain/protojs package
3. Generating documentation in HTML or Markdown from the comments of @nibiruchain/nibijs

---

## 🔓 License

This software is licensed under the MIT license. See [LICENSE](https://github.com/NibiruChain/ts-sdk/blob/main/LICENSE) for full disclosure.

© 2023 Nibi, Inc.

<p align="center">
<img src="https://raw.githubusercontent.com/NibiruChain/ts-sdk/main/img/nibi-logo-onwhite.png" style="width:200px">
</p>
