@tessera/sdk

Provider SDK for Tessera — the cross-provider identity & co-usage graph for the agentic x402 / MPP economy on Solana.

Install once, hook settle, and see the account behind the wallet — for your own paying wallets only. This is account-resolution, not network surveillance (ТЗ §6.6).

Install

npm install @tessera/sdk
# @solana/web3.js is an optional peer dependency (only for on-chain helpers)

Requires Node ≥ 18 (uses the global fetch).

Quickstart

import { Tessera, withTesseraAttest } from '@tessera/sdk';

const tessera = new Tessera({ apiKey: process.env.TESSERA_API_KEY! });

// One hook on your x402 / MPP settle pipeline (ТЗ §6.4)
const onSettle = withTesseraAttest(tessera);

// ...inside your settle handler:
await onSettle({
  payerId: payerWallet,      // raw wallet — hashed locally, never transmitted
  endpointClass: 'inference',
  amountUsdc: 0.02,
  txRef: settlementSignature,
});

// Enrichment for your own paying wallet
const enrichment = await tessera.enrich(payerWallet);

API (ТЗ §4.3)

| Method | Description | | --- | --- | | tessera.attest(settleEvent) | Emit a privacy-preserving attestation on settle. Returns the ingest receipt. | | tessera.enrich(wallet) | Enrichment (cluster, co-usage, churn-risk) for one of your own paying wallets. Free. | | tessera.query(spec) | Paid graph read over your wallets. Charges $TESS (burn / contributor pool / treasury split). | | tessera.stats() | Summary of your own slice: wallets, clusters, edges, contribution, $TESS earned, plus integrity/slash status and reward history. |

attest(settleEvent)

await tessera.attest({
  payerId,                 // required — raw payer wallet (base58)
  endpointClass: 'search', // default 'other'
  amountUsdc: 0.5,         // OR amountBucket: 'small'
  ts,                      // default now()
  txRef,                   // on-chain signature for reconciliation
});

The attestation is privacy-preserving: the SDK computes sha256("tessera-payer-commit-v1:" + payerId) locally and only submits the commit, endpoint class, amount bucket and timestamp — the raw wallet never leaves your process (ТЗ §3).

query(spec)

const { payment, results } = await tessera.query({
  wallets: [w1, w2],
  signalType: 'all',   // 'cluster' | 'co-usage' | 'churn' | 'all'
  window: '30d',       // '24h' | '7d' | '30d' | 'all'
});

Ownership guard

Every enrich / query is restricted to wallets that have paid you. A wallet you don't own returns 403:

import { TesseraApiError } from '@tessera/sdk';

try {
  await tessera.enrich(someWallet);
} catch (e) {
  if (e instanceof TesseraApiError && e.isForbidden) {
    // wallet has not paid you — enrichment denied
  }
  if (e instanceof TesseraApiError && e.isPaymentRequired) {
    // insufficient $TESS for a paid query
  }
}

On-chain transparency (ТЗ v1.1)

Payment is settled on-chain with a transparent split — burn / contributor pool / treasury (ТЗ §7.3). The payment object returned by query() reflects that split:

const { payment } = await tessera.query({ wallets });
// payment.burned      → SPL burn on the paid read
// payment.toContributors → on-chain reward pool (ТЗ §4.4 Reward Distribution)
// payment.toTreasury  → protocol treasury

Contributor rewards and stake slashing are on-chain in v1.1 (ТЗ §4.4 Slash Program / Reward Distribution) — no longer imitated. The SDK surface stays the four calls from ТЗ §4.3; integrity/stake and slash history are surfaced in the Stake UI with Solscan links (ТЗ §8.6).

Config

new Tessera({
  apiKey: 'tsk_...',              // required
  baseUrl: 'http://localhost:4000', // default
  timeoutMs: 15000,                 // default
  fetch: customFetch,               // optional (tests / edge runtimes)
});

Development

npm install
npm run typecheck
npm run build      # bundles ESM + CJS + d.ts into dist/
npm run example    # runs examples/quickstart.ts against a local backend

MIT · Part of the Tessera protocol. $TESS is a utility token (Token-2022, 6 decimals) with on-chain burn, contributor rewards and slashable stake (ТЗ v1.1 §7).