@thru/wallet

View as Markdown

@thru/wallet is the public wallet integration package. It combines the browser iframe SDK, shared wallet protocol/types, React hooks, and prebuilt React UI behind one package.

Install

npm install @thru/wallet @thru/sdk

Entry Points

Import	What it provides
`@thru/wallet`	Browser SDK, wallet protocol exports, wallet account types, connection helpers, transaction intent types, signing-context types, and signing-session types.
`@thru/wallet/react`	`ThruProvider`, `useWallet`, `useAccounts`, `useThru`, and related React types.
`@thru/wallet/react-ui`	`ThruAccountSwitcher` prebuilt React wallet control.

Native entrypoints also exist in the package, but this page focuses on the browser and React wallet surface.

Browser SDK

Use the root entrypoint when you want direct control of the embedded wallet iframe and wallet lifecycle.

import { BrowserSDK } from "@thru/wallet";

const wallet = new BrowserSDK({
  iframeUrl: "https://wallet.thru.org/embedded",
  rpcUrl: "https://rpc.alphanet.thru.org",
});

await wallet.initialize();

wallet.on("connect", ({ accounts }) => {
  console.log("Connected accounts", accounts);
});

const result = await wallet.connect({
  metadata: {
    appId: window.location.origin,
    appName: "My Thru App",
    appUrl: window.location.origin,
  },
});

const thru = wallet.getThru();
const account = await thru.accounts.get(result.accounts[0].address);

The root package also exports wallet protocol types such as WalletAccount, ConnectResult, ThruSigningContext, ThruTransactionIntent, ThruTransactionReviewPayload, ThruSigningSession, and ErrorCode.

React

Use @thru/wallet/react for React apps that want provider state and hooks.

import { ThruProvider, useWallet } from "@thru/wallet/react";

export function App({ children }: { children: React.ReactNode }) {
  return (
    <ThruProvider
      config={{
        iframeUrl: "https://wallet.thru.org/embedded",
        rpcUrl: "https://rpc.alphanet.thru.org",
      }}
    >
      {children}
    </ThruProvider>
  );
}

export function ConnectButton() {
  const { connect, isConnected, isConnecting } = useWallet();

  return (
    <button onClick={() => connect()} disabled={isConnected || isConnecting}>
      {isConnected ? "Connected" : "Connect wallet"}
    </button>
  );
}

Use @thru/wallet/react-ui when you want the prebuilt account switcher:

import { ThruProvider } from "@thru/wallet/react";
import { ThruAccountSwitcher } from "@thru/wallet/react-ui";

export function Header() {
  return <ThruAccountSwitcher />;
}

Sign A Transaction Intent

Use signTransaction(...) with a ThruTransactionIntent. The wallet owns fee payer selection, account ordering, headers, nonces, final wire transaction construction, and signing.

function bytesToBase64(bytes: Uint8Array): string {
  let binary = "";
  for (let i = 0; i < bytes.length; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return btoa(binary);
}

const signedBase64 = await wallet.signTransaction({
  walletAddress,
  programAddress,
  instructionData: bytesToBase64(instructionData),
  readWriteAddresses,
  readOnlyAddresses,
  review: {
    appName: "My Thru App",
    programAddress,
    instruction: "Transfer",
  },
});

instructionData is the base64-encoded program instruction payload. The returned value is the signed raw transaction encoded as base64.

Signing Context

Call getSigningContext() before building transactions that depend on signer or fee-payer identity. The selected managed account can differ from the public key that signs and pays for network submission.

const context = await wallet.getSigningContext();

console.log(context.selectedAccountPublicKey);
console.log(context.feePayerPublicKey);
console.log(context.signerPublicKey);

Signing Sessions

Use signing sessions when a connected app needs a temporary wallet-owned signer for repeated actions.

This example reuses the bytesToBase64 helper from the transaction intent example.

const session = await wallet.createSigningSession({
  walletAddress,
  durationSeconds: 60 * 30,
});

const signedBase64 = await session.signTransaction({
  programAddress,
  instructionData: bytesToBase64(instructionData),
  readWriteAddresses,
  readOnlyAddresses,
});

await session.revoke();

The browser SDK also exposes createSigningSessionInstruction(...), confirmSigningSession(...), getSigningSession(...), getSigningSessions(...), and revokeSigningSession(...).