resolveTIN — read a TIN account from Solana

Reads a TIN account, decodes its identity route, and reports whether the stored record is ready for current TSN settlement use.

What it does

resolveTIN reads the requested TIN from the configured Solana connection. It first checks the current TIN registry PDA, then falls back to scanning the program for the legacy account layout when no current registry exists. The result includes the display name, account kind, route commitments, status, and whether the stored encrypted material requires an upgrade.

How the flow works

1. Caller invokes the function

   The caller supplies a TIN, a Solana Connection, and optionally the TIN program ID. A lookup secret can be supplied for the private resolver path.

2. Validation

   The SDK derives the current registry PDA and requests the account. If the account is absent, it searches the program for a matching legacy TIN account. If neither exists, it throws a not-found error.

3. Main work

   The SDK decodes the account, checks the stored route and encrypted master-seed envelope, and maps the on-chain fields into a resolved identity object. A supplied lookupSecret selects the private resolution path.

4. Result

   The promise resolves with the TIN, display name, authority account, account kind, readiness flags, and route commitments. No account is modified.

Signature

export async function resolveTIN(params: {
  tin: bigint | number | string;
  connection: Connection;
  programId?: PublicKey | string | null;
  lookupSecret?: Uint8Array | string;
  sensitiveAuthorizations?: Record<string, Uint8Array | string>;
}): Promise<TinResolvedIdentity>;

Errors

Error	When it occurs
TIN <value> was not found in TIP program <program>	Neither the current registry PDA nor a legacy account matches the TIN.
Resolver errors from the Solana connection	The RPC request fails or returns malformed account data.

Example

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

const identity = await resolveTIN({
  tin: "1234567890",
  connection: new Connection("https://api.devnet.solana.com"),
});

console.log(identity.name, identity.accountKind, identity.upgradeRequired);

Source

tins.ts:1484