Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Lifecycle & Transport

SDK initialization, serialization, transport errors, and gRPC configuration.

Package runtime

The published package is ESM (type: module) and expects @mysten/sui >=2.0.0 <3.0.0 as a peer dependency. Import the package through its root export; do not rely on the repository's internal source paths.

Initialization

The public factory is asynchronous and accepts an optional final abort signal:

const controller = new AbortController();
const sdk = await Aftermath.create(
  {
    network: "MAINNET",
    // baseUrl, fullnodeUrl, apiEndpoint, addresses, or api are optional
  },
  controller.signal,
);

AftermathOptions supports network, baseUrl, fullnodeUrl, apiEndpoint (defaults to api), preloaded addresses, or a pre-built AftermathApi. baseUrl overrides the API host; fullnodeUrl is passed to both SuiGrpcClient.baseUrl and SuiJsonRpcClient.url. Supplying addresses or api avoids address discovery.

Canonical hosts in v3.3.1:

Network
API
Sui fullnode

MAINNET

https://aftermath.finance

https://fullnode.mainnet.sui.io:443

DEVNET

https://devnet.aftermath.finance

https://fullnode.devnet.sui.io:443

LOCAL

http://localhost:3000

http://127.0.0.1:9000

The effective HTTP URL is {baseUrl}/{apiEndpoint}/{provider-prefix}/{path}. For a custom service mounted without /api, set apiEndpoint: ""; do not hard-code /api into a provider path.

Request and response serialization

Caller.fetchApi sends GET when the body is undefined, and POST for every defined body (including {}). It sets Content-Type: application/json and adds Authorization: Bearer <accessToken> when Auth.init has installed a token.

The SDK's JSON replacer converts a JavaScript bigint to a string with an n suffix, for example 123n → "123n". Normal responses use Helpers.parseJsonWithBigint to revive safe "123n" values to bigint. Pass disableBigIntJsonParsing only when a provider explicitly requires raw JSON. Do not assume every number is a BigInt: timestamps, prices, booleans, and counts remain ordinary JSON values.

Transaction helpers behave as follows:

  • fetchApiTransaction parses a bare serialized transaction as a Sui Transaction, using Transaction.fromKind for txKind: true and Transaction.from otherwise.

  • fetchApiTxObject parses response.txKind with Transaction.from when the response also has sponsorSignature; otherwise it uses Transaction.fromKind.

  • A request walletAddress is applied as the transaction sender after parsing.

Abort and transport errors

The v3.3.1 AftermathTransportError is exported from the package root:

kind is one of:

Kind
Meaning
Useful fields

http

Server returned a non-2xx response

status, retryAfterMs

network

Fetch/DNS/socket failure

cause, code

abort

Caller-owned signal was aborted

abortSource: "caller"

timeout

Timeout or timeout-like fetch failure

abortSource: "timeout", code

decode

A successful response was not valid JSON

cause

HTTP errors preserve the old Error name and message format: HTTP <status> <statusText>: <body>. Retry-After is parsed into retryAfterMs for integer seconds or valid HTTP dates.

Retry reads and bootstrap calls on transient network, timeout, 429, and 5xx failures when safe. Do not blindly retry transaction submission or a request whose bytes may already have been accepted; reconcile chain/account state first. Treat caller aborts as intentional cancellation.

gRPC-first AftermathApi

Construct the low-level provider with a SuiGrpcClient, resolved config addresses, and optionally a SuiJsonRpcClient:

The current source describes the optional JSON-RPC surface as three legacy helpers: Events().fetchCastEventsWithCursor, Transactions().fetchTransactionsWithCursor, and deprecated Sui().fetchSystemState. AftermathApi.requireJsonRpcClient() throws a descriptive error when those helpers are called without a JSON-RPC client. Every other current AftermathApi call is intended to use gRPC. Prefer the Aftermath service's high-level providers for events, transaction history, and system state where possible.

Last updated