TIN Identity and Wallet Recovery

How applications resolve a TIN and how its owner recovers it with the TSN SDK.

A TIN is a 10-digit transfer identity managed by TIP. The owner shares the TIN with a sender, who can resolve and review its owner-provided display name before authorizing a payment. A display name is a confirmation aid, not legal identity verification.

The TIP registry keeps identity data encrypted. The owner’s recovery record lives in a separate on-chain PDA owned by the TIN Registrar program; it is not a field in the main registry account. When the owner reconnects their wallet, the SDK locates the recovery record and decrypts the envelope locally.

Resolve a TIN

TIN resolution uses a protected lookup secret and should run only in an application environment that can keep that secret private. Never put it in browser code, wallet messages, or publicly accessible configuration.

import { Connection } from "@solana/web3.js";
import { resolveTinV1Identity } from "@trustlink/tsn-sdk/tins";

const recipient = await resolveTinV1Identity({
  connection: new Connection(process.env.TSN_RPC_URL!, "confirmed"),
  tin: recipientTin,
  lookupSecret: process.env.TINS_LOOKUP_SECRET!,
  programId,
});

if (!recipient) throw new Error("TIN could not be resolved");
console.log(recipient.displayName);

For creation, the connected owner authorizes a TIN identity and recovery envelope through the SDK. The wallet’s secret key remains in the wallet; the application handles the returned encrypted data and follows the SDK’s request flow.

The SDK reference documents the creation and recovery helpers. Issuer-side configuration, request validation, and on-chain staging details are maintained in the repository documentation.