Wallet Bridge

Wallet Bridge is a feature of the Net website's storage content renderer that enables HTML content stored in Net Storage to securely interact with the user's connected wallet. When the Net website displays HTML content from Storage, it can optionally enable Wallet Bridge to provide a safe way for stored web applications to request wallet operations like signing messages, sending transactions, and reading wallet information.

What is Wallet Bridge?

Wallet Bridge is a secure communication layer provided by the Net website's renderer when displaying HTML content from Net Storage. It is not part of the Storage protocol itself, but rather a feature of how the Net website chooses to render stored HTML content. When enabled, the renderer injects a window.wallet object into the iframe that provides wallet interaction methods.

Key features:

• Secure message passing between iframe and parent window
• User confirmation dialogs for all wallet operations
• Automatic validation of requests
• Support for common wallet operations (signing, transactions, queries)

Use cases:

• Interactive dApps stored in Net Storage
• Onchain games and applications
• Wallet-enabled web content
• Custom transaction interfaces

How it Works

Wallet Bridge uses a secure postMessage-based communication pattern:

1. Storage page renders HTML in an iframe with wallet bridge enabled
2. Bridge injection: The IframeWalletBridge class is injected as window.wallet into the iframe
3. Iframe calls methods: Content calls methods on window.wallet (e.g., window.wallet.getAccount())
4. Request sent: Requests are sent via postMessage to the parent window
5. Validation: Parent validates the request (origin, structure, timestamp)
6. User confirmation: Parent shows a confirmation dialog to the user
7. Execution: Parent executes the wallet operation via the connected wallet
8. Response: Result is sent back via postMessage to the iframe

Security features:

• Origin validation: Only blob: and same-origin messages accepted
• Message structure validation
• Request ID and timestamp validation (30s timeout)
• Confirmation dialogs for all operations
• Iframe ID isolation to prevent duplicate dialogs

When is it Available?

Wallet Bridge is only available when:

• The Net website's storage renderer has wallet bridge enabled (enabled by default on storage pages)
• The user has a wallet connected
• The content is HTML and rendered in an iframe

Important: Wallet Bridge is a feature of the Net website's renderer, not Storage itself. Any renderer for displaying Net Storage content should implement wallet bridge functionality to enable stored HTML applications to interact with user wallets. If Wallet Bridge is not available, window.wallet will be undefined.

Available Functions

getAccount()

Returns the connected wallet address.

Returns: string - The wallet address (e.g., "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6")

Example:

const account = await window.wallet.getAccount();
console.log("Connected account:", account);

getChainId()

Returns the current chain ID.

Returns: number - The chain ID (e.g., 8453 for Base)

Example:

const chainId = await window.wallet.getChainId();
console.log("Current chain:", chainId);

getBalance()

Returns the wallet balance in wei.

Returns: string - The balance in wei as a decimal string

Example:

const balance = await window.wallet.getBalance();
console.log("Balance (wei):", balance);

signMessage(message)

Signs a message using the connected wallet.

Parameters:

• message (string): The message to sign

Returns: string - The signature

Example:

const signature = await window.wallet.signMessage("Hello, Net Protocol!");
console.log("Signature:", signature);

signTypedData(typedData)

Signs EIP-712 typed data using the connected wallet.

Parameters:

• typedData (object): EIP-712 typed data structure with domain, types, primaryType, and message

Returns: string - The signature

Example:

const typedData = {
  domain: {
    name: "Net Protocol",
    version: "1",
    chainId: 8453,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  },
  types: {
    Message: [
      { name: "content", type: "string" },
      { name: "timestamp", type: "uint256" },
    ],
  },
  primaryType: "Message",
  message: {
    content: "Hello, Net Protocol!",
    timestamp: Math.floor(Date.now() / 1000),
  },
};

const signature = await window.wallet.signTypedData(typedData);

sendTransaction(params)

Sends a transaction using the connected wallet.

Parameters:

• params (object): Transaction parameters
  • to (string): Recipient address (required)
  • value (string): Value in wei as decimal string (required)
  • data (string, optional): Transaction data (hex string)
  • gasLimit (string, optional): Gas limit
  • gasPrice (string, optional): Gas price

Returns: string - The transaction hash

Example:

const hash = await window.wallet.sendTransaction({
  to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  value: "1000000000000000", // 0.001 ETH in wei
  data: "0x...", // Optional function call data
});
console.log("Transaction hash:", hash);

encodeFunctionCall(abi, functionName, params)

Encodes a Solidity function call into calldata.

Parameters:

• abi (array): Function ABI definition
• functionName (string): Name of the function to encode
• params (array): Function parameters

Returns: object with:

• calldata (string): Encoded function call data (hex string)
• warning (string): Warning message about verifying transaction details

Example:

const abi = [
  {
    type: "function",
    name: "transfer",
    inputs: [
      { name: "to", type: "address" },
      { name: "amount", type: "uint256" },
    ],
  },
];

const result = await window.wallet.encodeFunctionCall(
  abi,
  "transfer",
  ["0x1234...", "1000000000000000000"]
);

// Use the calldata in a transaction
const hash = await window.wallet.sendTransaction({
  to: tokenAddress,
  data: result.calldata,
  value: "0",
});

Error Handling

All Wallet Bridge functions return promises that reject on error. Common errors include:

• WALLET_NOT_CONNECTED: No wallet is connected
• USER_REJECTED: User cancelled the operation
• INVALID_INPUT: Invalid parameters provided
• SIGN_FAILED: Message signing failed
• SEND_FAILED: Transaction submission failed
• ENCODING_FAILED: Function encoding failed

Example error handling:

try {
  const account = await window.wallet.getAccount();
  console.log("Account:", account);
} catch (error) {
  console.error("Error:", error.message);
  // Handle error appropriately
}

Security Considerations

• User confirmation required: All wallet operations require explicit user confirmation via a dialog
• Content validation: Users should verify that the content requesting wallet operations is from a trusted source
• Transaction review: Always review transaction details in the confirmation dialog before approving
• Content can be created by anyone: Remember that HTML content in Net Storage can be created by anyone - use at your own risk

Complete Example

See the Wallet Bridge Example page for a complete working example with all functions demonstrated.