TSN SDK — Build signed settlement clients

Reference for the application-facing TypeScript SDK, including network status, TIP/TIN identity, payment authorization, and cross-chain helpers.

@trustlink/tsn-sdk is the application-facing TypeScript façade. It exports the client, authorization, TIN, cross-chain, wallet-transfer, receipt, recovery, and Solana helpers from src/index.ts.

The snippets illustrate integration stages and assume caller-supplied variables. Complete typed examples and the full generated reference provide verified inputs and signatures.

Public modules and functions

The exports below are grouped by source module. The linked source is authoritative for the complete parameter type and return shape.

Module	Public exports documented in source
client	TsnHttpClient with post, get, patch, postIntent, listPendingIntentWork, updateIntentStatus.
network-status	getTsnNetworkStatus; TsnNetworkStatus, TsnServiceStatus, and option types.
payment-authorization	createSenderPaymentAuthorizationMessage, createPaymentAuthorizationNonce, createPaymentAuthorizationExpiry, createPaymentAuthorization, createTcapAssetPaymentAuthorization, createCrossChainPaymentAuthorization, buildPaymentAuthorizationIntentRequest. createTcapAssetPaymentAuthorization resolves the active TCAP asset and its token ID/decimals before producing the signed payment message. Submit the resulting request with TsnHttpClient.postIntent; there is no submitPaymentAuthorizationToMempool helper.
wallet-transfer	buildTsnSplTokenTransferTransaction.
cross-chain	validateCrossChainRecipient, validateCreditcoinPayoutAuthorization, validateCreditcoinDestination, createTinExitReplayKey, assertVerifiedDestinationLiquidity, CreditcoinRouteClient, loadCrossChainUiSnapshot, TsnCrossChainClient.
tins	TIN V1 registry lookup, creation-envelope, owner-recovery, creation intent, and submission helpers. The SDK does not expose retired plaintext TIN account decoders or direct-create instruction builders.
Other exported modules	contracts, canonical-message, mempool, quote, send-estimate, settlement-economics, program, token-registry, payment-authorization-server, payment-jobs, tsn-exit, blockchain/*, gpru, tin-envelopes, tin-device-*, receipts, authorization, recovery, sessions, and device.

Network status

import { getTsnNetworkStatus } from "@trustlink/tsn-sdk";

const status = await getTsnNetworkStatus({
  live: {
    node: process.env.TSN_NODE_URL,
    receiver: process.env.TSN_RECEIVER_URL,
    rpc: process.env.TSN_RPC_URL,
  },
});

if (!status.readyForNativeTransactions) throw new Error("TSN core services are unavailable");

The application supplies endpoint values; the SDK does not read the application’s .env file. When both local and live endpoints are supplied, it prefers a reachable local endpoint before the configured live one. Native readiness requires the configured Node, Receiver, and RPC gateway to respond. Cross-chain readiness additionally requires a registered destination route. The Cranker is a transaction-submission role, not a public application HTTP dependency.

Payment authorization

import { Connection, PublicKey } from "@solana/web3.js";
import {
  TsnHttpClient,
  buildPaymentAuthorizationIntentRequest,
  createTcapAssetPaymentAuthorization,
} from "@trustlink/tsn-sdk";

const authorization = await createTcapAssetPaymentAuthorization({
  connection: new Connection(rpcUrl, "confirmed"),
  depositor: new PublicKey(senderWallet),
  mint: new PublicKey(tokenMintAddress),
  senderWallet,
  senderIdentity: senderWallet,
  receiverIdentity: `tin:${recipientTin}`,
  recipientDisplayName: recipient.displayName,
  recipientDisplayNameSource: recipient.displayName.trim() ? "owner-provided" : "not provided",
  amount,
  senderFeeAmount,
  totalTokenRequiredUi: amount + senderFeeAmount,
  fundingMode: "tcap_deposit_v2",
});
const signature = await wallet.signMessage(
  new TextEncoder().encode(authorization.message),
);

const request = buildPaymentAuthorizationIntentRequest({
  paymentId,
  recipientHash: recipient.ownerPubkeyHash,
  recipientTin,
  tokenMintAddress: authorization.asset.mint,
  tokenDecimals: authorization.asset.decimals,
  senderWallet,
  senderAuthorizationMessage: authorization.message,
  senderAuthorizationSignature: signatureBase64,
  senderAuthorizationNonce: authorization.nonce,
  senderAuthorizationIssuedAt: authorization.issuedAt,
  senderAuthorizationExpiresAt: authorization.expiresAt,
  senderFeeAmount,
  senderSignedFundingTransaction,
  senderFundingMode: "tcap_deposit_v2",
  amount,
});
const client = new TsnHttpClient({ baseUrl: process.env.TSN_NODE_URL! });
const intent = await client.postIntent(request);

The application separately constructs and wallet-signs the reserve deposit transaction. Node resolves the TIN’s current TIP route itself; do not add route commitments or the protected lookup secret to the sender authorization or intent request. Current Node validation accepts tcap_deposit_v2, not retired wallet-only or PRU funding modes.

TIN V1 lookup and recovery

resolveTinV1Identity derives the registry PDA from the TIN and TIP program ID, reads the account through the supplied Solana connection, validates the account’s version and keyed lookup commitment, and decrypts the identity envelope using the supplied lookup secret. Call it only in a trusted application environment where that secret is protected. Never bundle the lookup secret into browser code or send it to Receiver or Cranker. The Node independently verifies the recipient registry state and route when it validates payment work.

TIN V1 creation encrypts the TIN and display name before they enter Receiver work. The SDK also provides owner-recovery PDA and envelope helpers so wallet recovery does not rely on public registry enumeration. Do not use retired resolveTIN or resolveTinRoute exports, raw legacy TIN account decoders, or direct-create instruction builders.

Source: index.ts, network-status.ts:79-157, payment-authorization.ts:1-258, tins.ts:1168-1630, cross-chain.ts:1-450