SupraWalletAdapter

A lightweight TypeScript adapter that enables DApps running in iframes to communicate with parent Multisig wallet applications via the postMessage API.

Installation

npm install supra-multisig-adapter

Overview

The SupraWalletAdapter provides a secure bridge between iframe-embedded DApps and their parent wallet applications. It handles:

• Wallet connection and disconnection
• Network and chain information retrieval
• Balance queries
• Transaction creation and signing
• Event subscription (account changes, disconnections)
• Automatic parent origin detection

Quick Start

Basic Usage

import { SupraWalletAdapter } from 'supra-multisig-adapter'

// Create adapter instance
const adapter = await createSupraMultisigAdapter();

if (adapter) {
  // Connect to wallet
  const address = await adapter.connect()
  console.log('Connected address:', address)

  // Get current network
  const network = await adapter.getNetwork()
  console.log('Current network:', network)

  // Get balance
  const balance = await adapter.balance()
  console.log('Balance:', balance)

  // Send a transaction
  try {
    const result = await adapter.sendTransaction({
      data: '0x...' // hex-encoded transaction data
    })
    console.log('Transaction result:', result)
  } catch (error) {
    console.error('Transaction failed:', error)
  }
} else {
  console.log('Adapter not available - likely not running in iframe')
}

Async Initialization

For cases where you need to ensure network information is loaded:

import { createSupraMultisigAdapter } from 'supra-multisig-adapter'

const adapter = await createSupraMultisigAdapter()

if (adapter) {
  // Adapter is ready with network info loaded
  const network = adapter.network()
}

Usage with Existing Provider (e.g. Starkey Wallet)

If your DApp already has a provider set up and you want to integrate the Supra multisig adapter without rewriting the whole logic:

useEffect(() => {
  async function initMultisigWalletAdapter() {
    const adapter = await createSupraMultisigAdapter();
    if (!adapter) return;

    setSupraProvider(adapter);
    setIsStarkeyInstalled(true);
    getNetworkData();
  }

  initMultisigWalletAdapter();
}, []);

API Reference

Core Methods

connect(): Promise<string>

Requests connection to the wallet and returns the connected account address.

disconnect(): Promise<void>

Disconnects from the wallet.

getNetwork(): Promise<string>

Retrieves the current network identifier (e.g., "mainnet").

getChainId(): Promise<{ chainId: string }>

Gets the current chain ID information.

balance(): Promise<{ balance: number, formattedBalance: number, decimal: number, displayUnit: string }>

Retrieves the current wallet balance.

sendTransaction<T>(transaction: { data: string }): Promise<T>

Sends a signed transaction to the network. The data field should contain hex-encoded transaction bytes.

createRawTransactionData(rawTxPayload: any[]): Promise<string>

• [0] senderAddr (string)
• [1] senderSequenceNumber (bigint)
• [2] moduleAddr (string)
• [3] moduleName (string)
• [4] functionName (string)
• [5] functionTypeArgs (TxnBuilderTypes.TypeTag[])
• [6] functionArgs (Uint8Array[])
• [7] optionalTransactionPayloadArgs (OptionalTransactionPayloadArgs | undefined)

Creates raw transaction data from the provided payload array containing transaction parameters.

Event Handling

on(event: WalletEvent, listener: (payload: unknown) => void): () => void

Subscribe to wallet events. Returns an unsubscribe function.

off(event: WalletEvent, listener: (payload: unknown) => void): void

Remove a specific event listener.

Available Events:

• 'accountChanged' - Fired when the connected account changes
• 'disconnect' - Fired when the wallet disconnects
• Custom string events

Factory Methods

SupraWalletAdapter.create(opts?: AdapterOptions): Promise<SupraWalletAdapter | null>

Creates an adapter instance, returning null if no valid parent origin can be determined.

createSupraWalletAdapter(opts?: AdapterOptions): Promise<SupraWalletAdapter | null>

Convenience function equivalent to SupraWalletAdapter.create().

Security Considerations

• The adapter automatically detects the parent origin from document.referrer
• If no specific origin can be determined, it falls back to "*"
• Always validate that you're running in the expected iframe context
• Use specific parent origins when possible via the parentOrigin option

Error Handling

All methods return Promises that reject with Error objects. Common error scenarios:

• Timeout errors (after 60 seconds by default)
• Invalid parent origin
• Wallet connection refused
• Transaction signing failures

try {
  await adapter.connect()
} catch (error) {
  if (error.message.includes('Timeout')) {
    console.log('Connection timed out')
  } else {
    console.error('Connection failed:', error.message)
  }
}

TypeScript Support

The adapter is written in TypeScript and provides full type definitions. Import types as needed:

import type {
  WalletEvent,
  AdapterOptions,
  ChainIdInfo
} from 'supra-multisig-adapter'

Browser Compatibility

Works in all modern browsers that support:

• postMessage API
• Promise (or with a polyfill)
• ES6 features (classes, arrow functions, etc.)

License

MIT License