@unconfirmed/onara

TypeScript client SDK for Onara — a policy-based Sui transaction sponsorship (gas station) server.

Install

bun add @unconfirmed/onara @mysten/sui

@mysten/sui is a peer dependency — the SDK uses whichever copy your app installs.

Usage

As a Sui client extension (recommended)

Register Onara on a Sui client with $extend, following the Mysten SDK extension pattern. The registered client is reused to build transactions, so you don't pass it again:

import { SuiGrpcClient } from '@mysten/sui/grpc'
import { onara } from '@unconfirmed/onara'

const client = new SuiGrpcClient({ network: 'testnet', baseUrl: 'https://fullnode.testnet.sui.io:443' })
  .$extend(onara({ url: 'https://my-onara.example.com' }))

// Sponsor a transaction — built, signed, and submitted for you
const result = await client.onara.sponsorTransaction({ transaction: tx, signer: keypair })

// Inspect the sponsor
const { address, balances } = await client.onara.status()

As a standalone client

import { OnaraClient } from '@unconfirmed/onara'

const onara = new OnaraClient('https://my-onara.example.com')

// Check sponsor status & view configured policies
const { address, balances } = await onara.status()
const policies = await onara.policies()

// High-level: build, sign, and sponsor (pass the Sui client used to build)
const result = await onara.sponsorTransaction({
  transaction: tx,
  signer: keypair,
  client: suiClient,
})

// Low-level: sponsor pre-built bytes
const result = await onara.sponsor({
  sender: '0x...',
  txBytes: '...',
  txSignature: '...',
  dryRun: true,
})

API

onara(options)

Returns a Sui client extension for client.$extend(...). Registers an OnaraClient under client.onara (or a custom name).

• url — base URL of the Onara server
• name? — property to register under (default 'onara')
• fetch? — custom fetch implementation

new OnaraClient(url) / new OnaraClient({ url, fetch?, client? })

Create a client directly. fetch injects a custom fetch (useful for testing); client sets a default Sui client for sponsorTransaction (set automatically when registered via onara()).

client.status()

Returns the server's network, chain identifier, sponsor address, and balances.

client.policies()

Returns the array of configured policy configs.

client.sponsor(options)

Submit pre-built transaction bytes for sponsorship.

• sender — Sui address of the transaction sender
• txBytes — base64-encoded transaction bytes
• txSignature — base64-encoded sender signature
• dryRun? — validate against policies without submitting
• waitForExecution? — wait for transaction finality (default true)
• simulate? — run pre-flight simulation before execution (default true)

On a confirmation timeout the thrown OnaraError carries digest and txStatus: 'unconfirmed'; use getTransactionStatus(digest) to resolve the final outcome.

client.sponsorTransaction(options)

High-level convenience that builds, signs, and sponsors a transaction.

• transaction — a Sui Transaction instance
• signer — a Sui Signer (e.g. Ed25519Keypair)
• client? — a Sui client used to build the transaction (defaults to the registered/constructed client)
• dryRun?, waitForExecution?, simulate? — as in sponsor

client.getTransactionStatus(digest)

Look up the on-chain status of a sponsored transaction by digest — useful for recovering after a confirmation timeout.