# @solworks/soltoolkit-sdk

> SolToolkit SDK, by SolWorks. A set of tools by developers for developers.

Latest version **0.0.37** (published 2024-10-15) · Affero GPL license · 0 weekly downloads

## Install

```sh
npm install @solworks/soltoolkit-sdk
pnpm add @solworks/soltoolkit-sdk
yarn add @solworks/soltoolkit-sdk
bun add @solworks/soltoolkit-sdk
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.37 |
| Published | 2024-10-15 |
| First published | 2022-09-13 |
| Weekly downloads | 0 |
| License | Affero GPL |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 105.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 37 |
| Author | Zhe SolWorks |
| Maintainers | zhesolworks |

## Links

- npm: https://www.npmjs.com/package/@solworks/soltoolkit-sdk
- Repository: https://github.com/SolWorks-Dev/soltoolkit-sdk
- Homepage: https://github.com/SolWorks-Dev/soltoolkit-sdk#readme
- Issues: https://github.com/SolWorks-Dev/soltoolkit-sdk/issues
- npm.io page: https://npm.io/package/@solworks/soltoolkit-sdk

## Dependencies (10)

- [bs58](https://npm.io/package/bs58.md) ^5.0.0
- [bn.js](https://npm.io/package/bn.js.md) ^5.2.1
- [decimal.js](https://npm.io/package/decimal.js.md) ^10.4.0
- [typescript](https://npm.io/package/typescript.md) ^4.8.2
- [@types/node](https://npm.io/package/@types/node.md) ^18.7.13
- [@types/bn.js](https://npm.io/package/@types/bn.js.md) ^5.1.0
- [@solana/web3.js](https://npm.io/package/@solana/web3.js.md) ^1.95.3
- [@solana/spl-token](https://npm.io/package/@solana/spl-token.md) ^0.3.4
- [@types/node-fetch](https://npm.io/package/@types/node-fetch.md) ^2.6.2
- [@solana/buffer-layout](https://npm.io/package/@solana/buffer-layout.md) ^4.0.0

## Recent versions

- 0.0.37 (latest) — 2024-10-15
- 0.0.36 — 2024-10-15
- 0.0.35 — 2024-10-15
- 0.0.34 — 2024-10-15
- 0.0.33 — 2024-10-11
- 0.0.32 — 2024-10-11
- 0.0.31 — 2024-10-07
- 0.0.30 — 2024-10-07
- 0.0.29 — 2024-10-07
- 0.0.28 — 2024-10-07
- 0.0.27 — 2024-07-09
- 0.0.26 — 2024-04-20
- 0.0.25 — 2024-04-20
- 0.0.24 — 2024-04-05
- 0.0.23 — 2024-04-04
- … 21 more at https://npm.io/package/@solworks/soltoolkit-sdk/versions

## README

<div align="center">
  <h1 style="margin-top:20px;">SolToolkit</h1>
  <p>
    <a href="https://www.npmjs.com/package/@solworks/soltoolkit-sdk"><img alt="SDK npm package" src="https://img.shields.io/npm/v/@solworks/soltoolkit-sdk" /></a>
    <a href="https://docs.solworks.dev/"><img alt="Docs" src="https://img.shields.io/badge/docs-tutorials-blueviolet" /></a>
    <a href="https://discord.com/invite/Qbd7yNcEPS"><img alt="Discord Chat" src="https://img.shields.io/discord/991631315768193067?color=blueviolet" /></a>
  </p>
</div>

# SolToolkit
This repository provides open source access to SolToolkit (Typescript) SDK.

## Installation
```
npm i @solworks/soltoolkit-sdk
```

## Modules

### ConnectionManager
ConnectionManager is a singleton class that manages web3.js Connection(s). It takes the following parameters on initialization using the async `getInstance()` method:
```typescript
{
    network: Cluster;
    endpoint?: string;
    endpoints?: string[];
    config?: ConnectionConfig;
    commitment?: Commitment;
    mode?: Mode;
}
```
#### Parameters
- `network` is the cluster to connect to, possible values are 'mainnet-beta', 'testnet', 'devnet', 'localnet'. This is required. If you do not pass in any values for `endpoint` or `endpoints`, the default endpoints for the network will be used.
- `endpoint` is a single endpoint to connect to. This is optional.
- `endpoints` is an array of endpoints to connect to. This is optional.
- `config` is a web3.js ConnectionConfig object. This is optional.
- `commitment` is the commitment level to use for transactions. This is optional, will default to 'max'.
- `mode` is the Mode for the ConnectionManager. This is optional, will default to 'single'. Possible values are:
  - 'single' - Uses the `endpoint` param, that falls back to the first endpoint provided in `endpoints`, that falls back to the default endpoints for the network.
  - 'first' - Uses the first endpoint provided in `endpoints`. Throws an error if no endpoints are provided.
  - 'last' - Uses the last endpoint provided in `endpoints`. Throws an error if no endpoints are provided.
  - 'round-robin' - Uses the endpoints provided in `endpoints` in a round-robin fashion (cycles through each endpoint in sequence starting from the first). Throws an error if no endpoints are provided.
  - 'random' - Uses a random endpoint provided in `endpoints`. Throws an error if no endpoints are provided.
  - 'fastest' - Uses the fastest endpoint provided in `endpoints`. Throws an error if no endpoints are provided.
  - 'highest-slot' - Uses the endpoint with the highest slot provided in `endpoints`. Throws an error if no endpoints are provided.

#### Methods
- `getInstance()` - Returns the singleton instance of the ConnectionManager. This method is async and must be awaited.
- `getInstanceSync()` - Returns the singleton instance of the ConnectionManager. This method is synchronous. This method should only be used after initializing the ConnectionManager with `getInstance()`.
- `conn()` - Returns a web3.js connection. This method will update the summary for each RPC to determine the 'fastest' or 'highest slot' endpoint. This method is async and must be awaited. 
- `connSync()` - Returns a web3.js connection. This method will use fastest' or 'highest slot' endpoint determined during initialization. This method is synchronous.

## Examples
### Fetching the fastest RPC endpoint
```typescript
import { ConnectionManager } from "@solworks/soltoolkit-sdk";

(async () => {
  // create connection manager
  const cm = await ConnectionManager.getInstance({
    commitment: "max",
    endpoints: [
      "https://api.devnet.solana.com",
      "https://solana-devnet-rpc.allthatnode.com",
      "https://mango.devnet.rpcpool.com",
      "https://rpc.ankr.com/solana_devnet",
    ],
    mode: "fastest",
    network: "devnet"
  });

  // get fastest endpoint
  const fastestEndpoint = cm._fastestEndpoint;
  console.log(`Fastest endpoint: ${fastestEndpoint}`);
})();
```

### Fetching the highest slot RPC endpoint
```typescript
import { ConnectionManager, Logger } from "@solworks/soltoolkit-sdk";

(async () => {
  // create connection manager
  const cm = await ConnectionManager.getInstance({
    commitment: "max",
    endpoints: [
      "https://api.devnet.solana.com",
      "https://solana-devnet-rpc.allthatnode.com",
      "https://mango.devnet.rpcpool.com",
      "https://rpc.ankr.com/solana_devnet",
    ],
    mode: "highest-slot",
    network: "devnet"
  });

  // get highest slot endpoint
  const highestSlotEndpoint = cm._highestSlotEndpoint;
  console.log(`Highest slot endpoint: ${_highestSlotEndpoint}`);
})();
```

### Fetching a summary of RPC speeds
```typescript
import { ConnectionManager, Logger } from "@solworks/soltoolkit-sdk";

(async () => {
  const logger = new Logger("example");

  // create connection manager
  const cm = await ConnectionManager.getInstance({
    commitment: "max",
    endpoints: [
      "https://api.devnet.solana.com",
      "https://solana-devnet-rpc.allthatnode.com",
      "https://mango.devnet.rpcpool.com",
      "https://rpc.ankr.com/solana_devnet",
    ],
    mode: "fastest",
    network: "devnet"
  });

  // get summary of endpoint speeds
  const summary = await cm.getEndpointsSummary();
  logger.debug(JSON.stringify(summary, null, 2));
})();
```

### Transfer SOL to 1 user
```typescript
import { Keypair, LAMPORTS_PER_SOL, Signer } from "@solana/web3.js";
import {
  ConnectionManager,
  TransactionBuilder,
  TransactionWrapper,
  Logger
} from "@solworks/soltoolkit-sdk";

const logger = new Logger("example");
const sender = Keypair.generate();
const receiver = Keypair.generate();

(async () => {
  // create connection manager
  const cm = await ConnectionManager.getInstance({
    commitment: COMMITMENT,
    endpoints: [
      "https://api.devnet.solana.com",
      "https://solana-devnet-rpc.allthatnode.com",
      "https://mango.devnet.rpcpool.com",
      "https://rpc.ankr.com/solana_devnet",
    ],
    mode: "fastest",
    network: "devnet",
  });

  // airdrop sol to the generated address
  const airdropSig = await cm
    .connSync({ airdrop: true })
    .requestAirdrop(sender.publicKey, LAMPORTS_PER_SOL);

  // confirm airdrop tx
  await TransactionWrapper.confirmTx({
    connectionManager: cm,
    changeConn: false,
    signature: airdropSig,
    commitment: "max",
  });

  // create builder and add token transfer ix
  var builder = TransactionBuilder
    .create()
    .addSolTransferIx({
      from: sender.publicKey,
      to: receiver.publicKey,
      amountLamports: 10_000_000,
    })
    .addMemoIx({
      memo: "gm",
      signer: sender.publicKey,
    });

  // build the transaction
  // returns a transaction with no fee payer or blockhash
  let tx = builder.build();

  // feed transaction into TransactionWrapper
  const wrapper = await TransactionWrapper.create({
    connectionManager: cm,
    transaction: tx,
    signer: sender.publicKey,
  }).addBlockhashAndFeePayer();

  // sign the transaction
  const signedTx = await wrapper.sign({
    signer: sender as Signer,
  });

  // send and confirm the transaction
  const transferSig = await wrapper.sendAndConfirm({
    serialisedTx: signedTx.serialize(),
  });
})();
```

### Send a memo to 1 user
```typescript
import { Keypair, LAMPORTS_PER_SOL, Signer } from "@solana/web3.js";
import {
  ConnectionManager,
  TransactionBuilder,
  TransactionWrapper,
  Logger
} from "@solworks/soltoolkit-sdk";

const logger = new Logger("example");
const sender = Keypair.generate();
const receiver = Keypair.generate();

(async () => {
  // create connection manager
  const cm = await ConnectionManager.getInstance({
    commitment: COMMITMENT,
    endpoints: [
      "https://api.devnet.solana.com",
      "https://solana-devnet-rpc.allthatnode.com",
      "https://mango.devnet.rpcpool.com",
      "https://rpc.ankr.com/solana_devnet",
    ],
    mode: "fastest",
    network: "devnet",
  });

  // airdrop sol to the generated address
  const airdropSig = await cm
    .connSync({ airdrop: true })
    .requestAirdrop(sender.publicKey, LAMPORTS_PER_SOL);

  // confirm airdrop tx
  await TransactionWrapper.confirmTx({
    connectionManager: cm,
    changeConn: false,
    signature: airdropSig,
    commitment: "max",
  });

  // create builder and add token transfer ix
  var builder = TransactionBuilder
    .create()
    .addMemoIx({
      memo: "gm",
      signer: sender.publicKey,
    });

  // build the transaction
  // returns a transaction with no fee payer or blockhash
  let tx = builder.build();

  // feed transaction into TransactionWrapper
  const wrapper = await TransactionWrapper.create({
    connectionManager: cm,
    transaction: tx,
    signer: sender.publicKey,
  }).addBlockhashAndFeePayer();

  // sign the transaction
  const signedTx = await wrapper.sign({
    signer: sender as Signer,
  });

  // send and confirm the transaction
  const transferSig = await wrapper.sendAndConfirm({
    serialisedTx: signedTx.serialize(),
  });
```

### Dispersing SOL to 10,000 users in <120 seconds
See [example](https://github.com/SolWorks-Dev/soltoolkit-sdk/blob/master/examples/bulk-sol-transfer.ts).


## License
SolToolkit is licensed under [Affero GPL](https://www.gnu.org/licenses/agpl-3.0.txt).

---
_Source: https://npm.io/package/@solworks/soltoolkit-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._