@okcontract/sdk/README.md

One-stop-shop permissionless SDK for building any blockchain frontend

# OKcontract SDK

### Overview

OKcontract SDK is a low-level library for managing smart contract
interactions. It interprets high-level inputs—like slippage, off-chain data,
and clear gas estimates—to produce transactions. You can explore prebuilt
interactions on the [OKcontract Interactions Hub](https://app.okcontract.com).

If you’re building with React, consider using the higher-level
[OKcontract SDK for React](https://github.com/okcontract/sdk-react).

### OKcontract Interactions Hub

Use the [OKcontract Interactions Hub](https://app.okcontract.com) to discover
smart contracts, view their ABIs, and choose methods and parameters for
interactions. An `interactionID` is automatically generated, such as
`AbX2IbtBDbgJdkAXucGu`.

The Hub also lets you:

- Name an interaction and add descriptive text
- Set allowances, pre-conditions, slippage
- Adjust the action button text
- And more

### Getting Started

#### Installation

Install both `cells` and `sdk`:

```bash
npm i --save @okcontract/cells @okcontract/sdk
```

#### Example

Below is a quick example of setting up an `OKContract` instance:

```ts
import { optimism } from "@okcontract/multichain";
import { type AppID, OKCore, baseOptions } from "@okcontract/sdk";

const id = "myApp" as AppID;
const core = new OKCore(baseOptions(id));
const page = new OKPage(core);
const proxy = page.proxy;

// Query an existing contract interaction on Optimism
const query = proxy.new("con:velodrome/router_optimism");
const chain = proxy.new(optimism.id);
const contract = new OKContract(page, query, chain);
```

See the
[OKcontract docs](https://docs.okcontract.com/sdk/reference/okcontract) for
details on this setup.

#### Demo

For a working demo, refer to [abi2ui](https://github.com/okcontract/abi2ui),
which provides the contract and token pages on the
[Hub](https://app.okcontract.com).

### Methods & Properties

A complete list of methods and properties is at
[docs.okcontract.com/sdk](https://docs.okcontract.com/sdk).

### Features

- **Less Manual Code:** Interactions reduce the amount of custom code needed
  for contract calls.
- **Transaction Computation:** Automatically handles gas estimates, slippage,
  and off-chain data.
- **Wallet Connection:** Connects to a user’s wallet, triggers transactions,
  and reads balances.
- **Onchain and Off-chain Data:** Synchronizes all required data for
  transactions.
- **Event Listening:** Monitors contract events to update UI state in real
  time.
- **Error Handling:** Surfaces clear error messages for failed transactions or
  data issues.
- **Multiple Chains:** Works with EVM-compatible blockchains (Starknet support
  coming).

### Design & Philosophy

The SDK is designed to be permissionless and easy to set up. No API key is
required.

### Documentation

For more examples and detailed explanations, visit
[docs.okcontract.com/sdk](https://docs.okcontract.com/sdk).

### License

The OKcontract SDK is built by [OKcontract](https://okcontract.com). The npm
package is available under the Apache license. The source repository will also
be released under an open source license.