> ## Documentation Index
> Fetch the complete documentation index at: https://trust-link-tsn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# tin-private-controller API

> Source-derived exports, parameter and result types, public methods and source links.

This reference is generated from the checked-out TypeScript exports. Types and signatures describe the package contract; source presence does not establish deployment or service availability. Error expressions below are direct throws, not an exhaustive list of failures from dependencies.

[Source module](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts). See the [reference index](https://trust-link-tsn.mintlify.site/sdk/api-reference.md) for package import boundaries and verification scope.

## buildTinV1OwnerEncryptionMessage

Import from `@trustlink/tsn-sdk`. [Implementation, line 47](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L47).

```ts theme={null}
buildTinV1OwnerEncryptionMessage(params: { ownerPublicKey: string; displayName: string; } & ({ resourceCommitment: string; nonce?: never; } | { nonce: Uint8Array; resourceCommitment?: never; })): Uint8Array<ArrayBuffer>
```

Direct failure expressions:

```text theme={null}
new Error("displayName must be a single printable line of at most 100 characters")
new Error("resourceCommitment must be 32-byte hex")
```

## configureTinMasterSeedThresholdProvider

Import from `@trustlink/tsn-sdk`. [Implementation, line 220](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L220).

```ts theme={null}
configureTinMasterSeedThresholdProvider(provider: TinMasterSeedThresholdProvider | null): void
```

## createTinPrivateIdentity

Import from `@trustlink/tsn-sdk`. [Implementation, line 304](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L304).

```ts theme={null}
createTinPrivateIdentity(params: { tin: string; routeVersion: number; routeNonce: string; ownerWallet: TinOwnerWallet; nodeRoutingPublicKeyBase64: string; masterSeed?: Uint8Array; }): Promise<{ pruConfigurationHash: string; encryptedMasterSeed: Uint8Array<ArrayBuffer>; encryptedPublicRouteEnvelope: Uint8Array<ArrayBuffer>; publicRoute: TinPublicRoutePayload; }>
```

## createTinV1OwnerSeedEnvelope

Creates the owner-recoverable seed envelope for a new TIN V1 intent.
The seed and signature-derived key stay in this runtime; only the encrypted
envelope is returned for inclusion in the owner-authorized creation intent.

Import from `@trustlink/tsn-sdk`. [Implementation, line 106](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L106).

```ts theme={null}
createTinV1OwnerSeedEnvelope(params: { ownerWallet: TinOwnerWallet; displayName: string; nonce: Uint8Array; }): Promise<{ resourceCommitment: string; encryptedMasterSeed: Uint8Array<ArrayBuffer>; gpruElgamalKeyVersion: 1; gpruElgamalPublicKey: Uint8Array<ArrayBufferLike>; gpruElgamalKeyCommitment: Uint8Array<ArrayBufferLike>; gpruBalanceScanKeyVersion: 1; gpruBalanceScanPublicKeyX: Uint8Array<ArrayBufferLike>; gpruBalanceScanPublicKeyY: Uint8Array<ArrayBufferLike>; }>
```

## getTinMasterSeedThresholdProvider

Import from `@trustlink/tsn-sdk`. [Implementation, line 226](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L226).

```ts theme={null}
getTinMasterSeedThresholdProvider(): TinMasterSeedThresholdProvider
```

Direct failure expressions:

```text theme={null}
new Error( "Authorized-device threshold encryption is not configured. TIN private data remains locked.", )
```

## loadTinPrivateTokenBalances

Import from `@trustlink/tsn-sdk`. [Implementation, line 722](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L722).

```ts theme={null}
loadTinPrivateTokenBalances(params: { tin: string; pruConfigurationHash: string; envelope: TinMasterSeedEnvelope | Uint8Array; ownerWallet: TinOwnerWallet; authorizedDevice?: TinAuthorizedDeviceSigner; thresholdProvider?: TinMasterSeedThresholdProvider; connection: Connection; tokens: TinBalanceTokenInput[]; signal?: AbortSignal; onProgress?: (message: string) => void; }): Promise<{ tokenBalances: { mint: string; decimals: number; balanceBaseUnits: string; }[]; pruBalances: { pruIndex: number; publicKey: string; mint: string; balanceBaseUnits: string; }[]; pruCount: number; activePruCount: number; nonZeroPruCount: number; }>
```

Direct failure expressions:

```text theme={null}
new DOMException("Aborted", "AbortError")
```

## prepareTinV1OwnerSeedAccess

Stable, reproducible wallet approval used to encrypt a TIN seed for later recovery.

Import from `@trustlink/tsn-sdk`. [Implementation, line 84](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L84).

```ts theme={null}
prepareTinV1OwnerSeedAccess(params: { ownerPublicKey: string; displayName: string; nonce: Uint8Array; }): Promise<{ resourceCommitment: string; message: string; }>
```

Direct failure expressions:

```text theme={null}
new Error("nonce must be 32 bytes")
```

## rewrapTinPrivateIdentityForWalletOwner

Re-encrypt an existing TIN seed for wallet-owned, any-device access without
changing its derived PRUs. A legacy device is used only once to open its old
envelope; it is never made part of the new envelope.

Import from `@trustlink/tsn-sdk`. [Implementation, line 391](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L391).

```ts theme={null}
rewrapTinPrivateIdentityForWalletOwner(params: { tin: string; pruConfigurationHash: string; envelope: TinMasterSeedEnvelope | Uint8Array; ownerWallet: TinOwnerWallet; routeVersion: number; routeNonce: string; nodeRoutingPublicKeyBase64: string; authorizedDevice?: TinAuthorizedDeviceSigner; thresholdProvider?: TinMasterSeedThresholdProvider; }): Promise<{ pruConfigurationHash: string; encryptedMasterSeed: Uint8Array<ArrayBuffer>; encryptedPublicRouteEnvelope: Uint8Array<ArrayBuffer>; publicRoute: TinPublicRoutePayload; }>
```

Direct failure expressions:

```text theme={null}
new Error( "This legacy TIN needs its existing device for a one-time any-device upgrade", )
new Error( `TIN master seed requires the ${envelope.provider} provider`, )
new Error( "The existing TIN seed does not match its registered PRU route", )
```

## TinBalanceTokenInput

Import from `@trustlink/tsn-sdk`. [Implementation, line 717](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L717).

```ts theme={null}
export type TinBalanceTokenInput = {
  mint: string;
  decimals: number;
};
```

## TinMasterSeedAccessContext

Import from `@trustlink/tsn-sdk`. [Implementation, line 183](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L183).

```ts theme={null}
export type TinMasterSeedAccessContext = {
  tin: string;
  ownerPublicKey: string;
  routeVersion: number;
  pruConfigurationHash: string;
  deviceSessionBinding: string;
  walletAuthorizationMessage: Uint8Array;
  walletAuthorizationSignature: Uint8Array;
  deviceAccessProof: TinDeviceAccessProof;
  resourceCommitment: string;
};
```

## TinMasterSeedThresholdProvider

The provider protects only a random data-encryption key. The master seed is
encrypted and decrypted locally by this controller and is never an input to
a threshold provider, Lit Action, TSN Node, backend, or Cranker.

Import from `@trustlink/tsn-sdk`. [Implementation, line 200](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L200).

### TinMasterSeedThresholdProvider.id

[Source, line 201](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L201).

```ts theme={null}
id: string
```

### TinMasterSeedThresholdProvider.getDeviceSessionBinding

[Source, line 202](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L202).

```ts theme={null}
getDeviceSessionBinding(): Promise<string>
```

### TinMasterSeedThresholdProvider.protectKey

[Source, line 203](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L203).

```ts theme={null}
protectKey(params: TinMasterSeedAccessContext): Promise<{ protectedKey: string; protectedKeyCommitment: string; accessControlHash: string; deviceKeyEnvelope: TinDeviceKeyEnvelope; }>
```

### TinMasterSeedThresholdProvider.releaseKey

[Source, line 209](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L209).

```ts theme={null}
releaseKey(params: TinMasterSeedAccessContext & { protectedKey: string; protectedKeyCommitment: string; accessControlHash: string; }): Promise<TinDeviceKeyEnvelope>
```

## TinOwnerWallet

Import from `@trustlink/tsn-sdk`. [Implementation, line 42](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L42).

```ts theme={null}
export type TinOwnerWallet = {
  publicKey: string;
  signMessage(message: Uint8Array): Promise<Uint8Array>;
};
```

## unlockTinPrivateRoute

Import from `@trustlink/tsn-sdk`. [Implementation, line 511](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L511).

```ts theme={null}
unlockTinPrivateRoute(params: { tin: string; pruConfigurationHash: string; envelope: TinMasterSeedEnvelope | Uint8Array; ownerWallet: TinOwnerWallet; authorizedDevice?: TinAuthorizedDeviceSigner; thresholdProvider?: TinMasterSeedThresholdProvider; }): Promise<{ prus: TinPublicRouteEntry[]; }>
```

Direct failure expressions:

```text theme={null}
new Error( "This legacy TIN needs a one-time wallet-authorized migration before it can be opened on any device", )
new Error( `TIN master seed requires the ${envelope.provider} provider`, )
new Error( "Locally derived PRUs do not match the TIN PRU configuration commitment", )
```

## withTinOwnerMasterSeed

Run an owner-only operation with the TIN master seed in memory. The SDK asks
the connected wallet to authorize access, verifies the envelope bindings,
and clears both the derived key and seed when the callback completes.
Callers should use this instead of exporting or persisting the seed.

Import from `@trustlink/tsn-sdk`. [Implementation, line 634](https://github.com/bigdreamsweb3/trustlink-pay/blob/main/tsn-protocol/sdks/tsn-sdk/src/tin-private-controller.ts#L634).

```ts theme={null}
withTinOwnerMasterSeed<T>(params: { tin: string; displayName: string; pruConfigurationHash: string; envelope: TinMasterSeedEnvelope | Uint8Array; ownerWallet: TinOwnerWallet; }, use: (masterSeed: Uint8Array) => Promise<T>): Promise<T>
```

Direct failure expressions:

```text theme={null}
new Error("TIN_MASTER_SEED_ENVELOPE_IDENTITY_MISMATCH")
new Error("TIN_MASTER_SEED_PROVIDER_REQUIRES_MIGRATION")
new Error("TIN_MASTER_SEED_REAUTHORIZATION_REQUIRED")
new Error("TIN_MASTER_SEED_ROUTE_COMMITMENT_MISMATCH")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.