TypeScript SDK

@nooschain/client is the TypeScript client for applications, publishing tools, browser clients, and operator automation that need to talk to a NOOSChain node. It wraps node HTTP APIs with typed builders, shared protocol schemas, canonical transaction signing, and focused helpers for buckets and smart contracts.

The SDK currently lives in the monorepo:

apps/nooschain-ts/

It imports transaction, payload, hash, and signing types from the core protocol boundary instead of maintaining a second copy of the chain schemas. When SDK helpers build transactions, they build the same payload shapes that validators execute.

Use the SDK when application code needs stable TypeScript types, canonical hashing, transaction signing, and structured errors. Use raw HTTP only for custom clients, protocol experiments, or tests that intentionally exercise the API boundary.

What The SDK Is For

Use case	SDK surface
Submit signed transactions	client.transactions
Read chain, block, protocol, mempool, and identity state	client.chain, client.mempool, client.identities
Work with buckets and encrypted records	client.buckets, client.transactions
Publish and call smart contracts	client.contracts
Sign transaction envelopes	TransactionSigner, PemTransactionSigner
Inspect operator-only diagnostics	client.observability, operator-token endpoints

Mental Model

The SDK does not execute chain rules locally and it does not write database rows directly. It is a typed client around the node API:

1. Query helpers read node or chain state.
2. Transaction builders create canonical transaction envelopes.
3. A signer signs the envelope.
4. client.transactions.submit(...) sends the signed transaction to the node.
5. The node accepts, validates, orders, and executes the transaction through the normal chain path.
6. Callers inspect receipts, transaction state, events, or call results after execution.

A successful submission means the node accepted the request for processing. It does not by itself mean consensus has finalized the transaction or that a smart contract call succeeded.

Operator endpoints are different: they expose local node diagnostics and require an operator token. Do not ship operator tokens in browser applications.

First Client

import { NooschainClient } from "@nooschain/client";

const client = new NooschainClient({
  baseUrl: "http://127.0.0.1:3000",
});

Operator-only endpoints need an operator token:

const operatorClient = new NooschainClient({
  baseUrl: "http://127.0.0.1:3000",
  operatorToken: process.env.NOOS_OPERATOR_TOKEN,
});

The client normalizes trailing slashes, applies request timeouts, parses JSON, and throws typed SDK errors for failed HTTP responses.

Signing And Nonces

Most write helpers need a signer:

import { PemTransactionSigner } from "@nooschain/client";

const signer = new PemTransactionSigner({
  publicKey: process.env.NOOS_SIGNER_PUBLIC_KEY!,
  privateKeyPem: process.env.NOOS_SIGNER_PRIVATE_KEY_PEM!,
});

Use nonce: "auto" when the SDK should ask the node for the signer's next nonce:

const built = await client.transactions.registerOrganization({
  signer,
  nonce: "auto",
  payload: {
    id: "org-example",
    name: "Example Organization",
    metadata: {},
  },
});

await client.transactions.submit(built.transaction);

This builds and submits transaction REGISTER_ORGANIZATION.

Automatic nonce resolution calls GET /identity/nonce and sends the signer public key in x-noos-signer-public-key-base64. Use explicit nonces for offline signing, custom batching, or external nonce coordination.

See Signing and Transactions.

First Query

Read helpers do not sign transactions:

const head = await client.chain.head();
console.log(head.height);
console.log(head.hash);

Some query groups expose public chain state. Others, especially observability and local runtime diagnostics, require an operator token because they describe the current node rather than only consensus state.

Buckets And Encrypted Records

The SDK has typed helpers for bucket transactions such as CREATE_BUCKET, bucket index schema updates, and prepared encrypted-record writes.

const { transaction, submission } =
  await client.transactions.submitAddEncryptedRecordFromPlaintext({
    signer,
    payload: {
      bucketId: "bucket-project-data",
      plaintextUtf8: JSON.stringify({ title: "Private payload" }),
    },
    publicQueryData: {
      projectId: "project-a",
      reviewed: false,
    },
    actorPublicKey: signer.publicKey,
  });

This helper asks the node to prepare the exact transaction ADD_ENCRYPTED_RECORD, signs that exact envelope, and submits it with the returned preparedTransactionId. User private keys are not sent to the node. Plaintext does reach the API in this flow.

For bucket concepts, encryption modes, schemas, and permissions, see Data Buckets and Permission Model. For SDK-specific record helpers, see Transactions and Querying.

Smart Contracts

The SDK can build smart contract manifests, hash WASM and manifests, publish code, instantiate contracts, grant bucket access, call methods, read ABI, query events, and fetch call results.

import { contractManifest } from "@nooschain/client";

const manifest = contractManifest({
  name: "report-store",
  version: "0.1.0",
  methods: {
    saveReport: {
      entrypoint: "saveReport",
      maxFuel: 250000,
      invoke: {
        allow: [{ principalType: "organization", principalId: "org-noos" }],
      },
      buckets: [],
    },
  },
});

const published = await client.contracts.publish({
  signer,
  nonce: "auto",
  submit: true,
  code: wasmBytes,
  contractId: "contract-report-store",
  manifest,
  ownerUserId: "user-admin",
  organizationId: "org-noos",
});

publish(...) builds the publish flow around transaction DEPLOY_CONTRACT_CODE and transaction INSTANTIATE_CONTRACT. For repeatable release artifacts, use publishPackage(...) with a contract package.

The SDK page explains the TypeScript helper calls. The deeper publishing, package, provenance, and registry rules live in:

• TypeScript SDK For Smart Contracts
• Publishing
• Packages And Provenance
• Package Provenance
• Contract Registry

Node And Browser Entry Points

Node.js tools can use filesystem helpers such as loadContractPackageFromDirectory(...), PEM keys loaded from disk, and operator tokens for administrative automation.

Browser apps can use shared transaction builders, query helpers, package descriptor validation helpers, and browser-compatible signing backends. Browser apps cannot use filesystem-backed package loaders, and they should not receive operator tokens or long-lived private keys.

PemTransactionSigner uses native node:crypto from the Node.js entrypoint and a browser-compatible libsodium-wrappers backend from the package browser export. Both sign the canonical transaction envelope.

Local Development

Build and test the SDK from the repository root:

npm run nooschain-ts:build
npm run nooschain-ts:test

Run the kitchen-sink example:

npm run nooschain-ts:kitchen-sink

The example reads NOOSCHAIN_SDK_BASE_URL and optional NOOSCHAIN_SDK_OPERATOR_TOKEN.

Section Guide

Page	Use it for
Getting Started	Client setup, imports, first transaction, first query.
Transactions	Typed transaction builders, submit flow, nonces, encrypted-record writes.
Querying	Chain, bucket, identity, mempool, and observability reads.
Signing	TransactionSigner, PEM signing, browser/custom custody.
TypeScript SDK For Smart Contracts	Publishing, calling, ABI, events, registry helpers, and contract metrics.
Errors	Structured SDK errors and caller handling.