@thru/embedded-provider

@thru/embedded-provider

Client-side provider for embedding the Thru wallet into any web application. Manages an iframe that hosts the wallet UI, communicates with it over postMessage, and exposes a simple API for connecting, signing transactions, and managing accounts.

Installation

npm install @thru/embedded-provider

Basic Usage

import { EmbeddedProvider } from "@thru/embedded-provider";

const provider = new EmbeddedProvider({
  iframeUrl: "https://wallet.thru.org",
});

// Initialize iframe (must be called before any other operation)
await provider.initialize();

// Connect to wallet (opens modal)
const result = await provider.connect();
console.log(result.accounts);

// Inspect the signing contract before building a transaction
const signingContext = await provider.thru.getSigningContext();

// Build your Thru transaction using signingContext.feePayerPublicKey, then sign it
const signed = await provider.thru.signTransaction(base64EncodedTx);

// Disconnect
await provider.disconnect();

// Cleanup when done
provider.destroy();

API

EmbeddedProvider

Main entry point. Creates and manages the wallet iframe.

Constructor

new EmbeddedProvider(config: EmbeddedProviderConfig)

Option	Type	Default	Description
iframeUrl	string	DEFAULT_IFRAME_URL	URL of the hosted wallet application
addressTypes	AddressType[]	[AddressType.THRU]	Chain types to enable

Methods

Method	Returns	Description
initialize()	Promise<void>	Create the iframe and wait for it to signal readiness
connect(options?)	Promise<ConnectResult>	Open the wallet modal and request a connection
disconnect()	Promise<void>	Disconnect the current session
isConnected()	boolean	Whether a wallet session is active
getAccounts()	WalletAccount[]	List of connected accounts
getSelectedAccount()	WalletAccount | null	Currently selected account
selectAccount(publicKey)	Promise<WalletAccount>	Switch the active account
mountInline(container)	Promise<void>	Mount the wallet inline inside a DOM element instead of as a modal
on(event, callback)	void	Subscribe to provider events
off(event, callback)	void	Unsubscribe from provider events
destroy()	void	Remove the iframe and clean up all listeners

Properties

Property	Type	Description
thru	IThruChain	Chain-specific interface for signing transactions on the Thru network

EmbeddedThruChain

Implements IThruChain. Accessed via provider.thru.

Method	Returns	Description
connect()	Promise<{ publicKey: string }>	Connect and return the Thru address
disconnect()	Promise<void>	Disconnect
getSigningContext()	Promise<ThruSigningContext>	Return the current selected account plus the actual fee payer/signer contract used by the embedded wallet
signTransaction(serializedTransaction)	Promise<string>	Accept a base64 signing payload or raw transaction and return canonical raw transaction bytes ready for submission

Events

Subscribe with provider.on(event, callback):

• connect -- Wallet connected successfully
• connect:start -- Connection flow initiated
• connect:error -- Connection attempt failed
• disconnect -- Wallet disconnected
• lock -- Wallet locked by the user
• account:changed -- Active account switched
• ui:show -- Wallet UI requested to be shown

Display Modes

The provider supports two display modes:

• Modal (default) -- The iframe is appended to document.body as a full-screen overlay.
• Inline -- The iframe is mounted inside a container element you provide, useful for embedding a connect button directly in your page layout.

// Inline mode
const container = document.getElementById("wallet-mount");
await provider.mountInline(container);

Security

The IframeManager validates that the iframe URL belongs to a set of trusted origins before loading it. Allowed origins:

• https://wallet.thru.org
• http://localhost (any port, for development)

Messages are sent with a strict targetOrigin and each iframe instance is tagged with a unique frame ID to prevent cross-talk.

Key Capabilities

• Iframe lifecycle management with automatic readiness detection
• Request/response correlation over postMessage with per-request timeouts
• Origin validation to prevent unauthorized wallet iframes
• Modal and inline display modes
• Event-driven architecture for connection state changes
• WebAuthn (passkey) support via iframe allow policy
• Chain-specific interfaces via the IThruChain abstraction

Thru Signing Contract

For the embedded passkey wallet, the selected wallet account shown in the UI can differ from the network fee payer / signer that actually authorizes the Thru transaction. Call provider.thru.getSigningContext() before building a transaction to retrieve:

• selectedAccountPublicKey - the managed account currently selected in the wallet
• feePayerPublicKey - the address that must be used as the transaction fee payer
• signerPublicKey - the cryptographic signer used by the wallet

signTransaction() always returns canonical Transaction.toWire() bytes encoded as base64, so apps can decode and submit the result directly without reordering signature bytes.

Dependencies

• @thru/chain-interfaces -- Shared chain interface types (IThruChain, WalletAccount)
• @thru/protocol -- Message type constants, request/response schemas, and helper utilities