Build dApps that feel at home in Bread

Quickstart

Three steps from an empty page to a confirmed transfer. React is the shortest path; the adapter also works on its own in plain TypeScript.

npm i @miden-sdk/miden-wallet-adapter \
  @miden-sdk/miden-sdk @miden-sdk/react

npm i @miden-sdk/miden-sdk \
  @miden-sdk/miden-wallet-adapter-miden \
  @miden-sdk/miden-wallet-adapter-base

import {
  MidenWalletAdapter,
  PrivateDataPermission,
  WalletAdapterNetwork,
  WalletProvider
} from '@miden-sdk/miden-wallet-adapter';

// Create adapters once, outside render: a new adapter disconnects the old one.
const wallets = [new MidenWalletAdapter({ appName: 'My dApp' })];

export function Root() {
  return (
    <WalletProvider
      wallets={wallets}
      network={WalletAdapterNetwork.Testnet}
      privateDataPermission={PrivateDataPermission.UponRequest}
    >
      <App />
    </WalletProvider>
  );
}

import { useEffect } from 'react';
import {
  MidenWalletName,
  PrivateDataPermission,
  SendTransaction,
  useWallet,
  WalletAdapterNetwork
} from '@miden-sdk/miden-wallet-adapter';

export function App() {
  const { wallet, select, connect, connected, address, requestSend, waitForTransaction } = useWallet();

  useEffect(() => {
    if (!wallet) select(MidenWalletName);
  }, [wallet, select]);

  async function pay(recipient: string, faucetId: string) {
    // WalletProvider connects with its own props; these arguments only satisfy the type.
    if (!connected) await connect(PrivateDataPermission.UponRequest, WalletAdapterNetwork.Testnet);
    const txId = await requestSend!(new SendTransaction(address!, recipient, faucetId, 'public', 1_000_000));
    const { txHash } = await waitForTransaction!(txId);
    console.log('committed', txHash);
  }

  return <button onClick={() => pay(RECIPIENT, FAUCET_ID)}>Pay with Bread</button>;
}

import { MidenWalletAdapter } from '@miden-sdk/miden-wallet-adapter-miden';
import {
  PrivateDataPermission,
  SendTransaction,
  WalletAdapterNetwork,
  WalletReadyState
} from '@miden-sdk/miden-wallet-adapter-base';

const adapter = new MidenWalletAdapter({ appName: 'My dApp' });

// The adapter polls for window.midenWallet and may find it at once, in its constructor.
if (adapter.readyState === WalletReadyState.Installed) enableConnectButton();
adapter.on('readyStateChange', state => {
  if (state === WalletReadyState.Installed) enableConnectButton();
});

async function pay(recipient: string, faucetId: string) {
  await adapter.connect(PrivateDataPermission.UponRequest, WalletAdapterNetwork.Testnet);
  const txId = await adapter.requestSend(
    new SendTransaction(adapter.address, recipient, faucetId, 'public', 1_000_000)
  );
  const { txHash, outputNotes } = await adapter.waitForTransaction(txId);
  return { txHash, outputNotes };
}

Connect and permissions

A connection is a grant from one account to one origin. You say what you want to read without asking each time; the user decides.

connect(
  privateDataPermission: PrivateDataPermission,
  network: WalletAdapterNetwork,
  allowedPrivateData?: AllowedPrivateData
): Promise<void>

Combine categories with a bitwise or, for example AllowedPrivateData.Assets | AllowedPrivateData.Notes.

What the user sees

• Approval screens name your site by its verified origin, never by a name you send.
• Connecting again from the same origin returns the saved grant without a prompt. A locked wallet asks the user to unlock first.
• Users review and revoke connections in Settings, Authorized DApps. disconnect() removes the session too.
• If the user turns off DApps Interaction in that screen, every request fails: the phone and desktop apps refuse it with NOT_GRANTED, the extension with a plain Not Found error.
• If Bread is not installed, connect() throws WalletNotReadyError. Through the React WalletProvider it also opens Bread's Chrome Web Store page.

Errors

Bread's refusals carry a code at the start of the message. Through the adapter most arrive wrapped in its Wallet...Error classes with the same message; importPrivateNote, requestConsumableNotes and a refused waitForTransaction pass the provider's error through as it is.

Networks

You name a network when you connect; Bread runs every request on the network the wallet is on.

• Bread accepts mainnet, testnet, devnet and localnet. Any other name is refused with NETWORK_NOT_GRANTED.
• Asking for a valid network the wallet is not on is not refused. The connect sheet tells the user: "This app asked for Miden Testnet, but your wallet is on Miden Mainnet." Requests then run on the wallet's network.
• mainnet is granted only while the wallet itself is on mainnet.

Read balances and notes

After connecting, address and publicKey are on the adapter. Everything else is a request, answered with a prompt or silently according to the grant.

import { NoteFilterTypes } from '@miden-sdk/miden-sdk';

const assets = await adapter.requestAssets();
// [{ faucetId, amount }]: faucetId as a bech32 address, amount as a decimal string

const consumable = await adapter.requestConsumableNotes();
const committed = await adapter.requestPrivateNotes(NoteFilterTypes.Committed);
// each: { noteId, senderAccountId, assets, noteType, nullifier, state }

const guardian = await adapter.requestGuardianInfo();
// { isGuardianAccount, guardianEndpoint, guardianProvider, guardianSyncStatus }

• requestPrivateNotes(filter, noteIds?) takes the SDK's NoteFilterTypes; pass NoteFilterTypes.List with ids to ask for specific notes.
• Every Bread account is a Guardian account. requestGuardianInfo reports its Guardian operator and sync state; the desktop provider does not implement it yet.

Transactions

Three shapes, one confirmation flow. Each call opens Bread's approval, and resolves with a transaction id once Bread has accepted the transaction.

import { SendTransaction } from '@miden-sdk/miden-wallet-adapter';

const txId = await adapter.requestSend(
  new SendTransaction(
    adapter.address, // sender: the connected account
    recipient,       // a Miden address
    faucetId,        // which token
    'private',       // 'public' or 'private' note
    250_000          // integer, smallest unit
  )
);

import { ConsumeTransaction } from '@miden-sdk/miden-wallet-adapter';

// Claim a note addressed to the connected account.
const txId = await adapter.requestConsume(
  new ConsumeTransaction(faucetId, noteId, 'public', amount)
);

// A private note the wallet has not seen yet travels with its bytes:
// new ConsumeTransaction(faucetId, noteId, 'private', amount, noteBytes)

import { Transaction } from '@miden-sdk/miden-wallet-adapter';
import type { TransactionRequest } from '@miden-sdk/miden-sdk';

// Build any TransactionRequest with the Miden SDK, then hand it to Bread.
const request: TransactionRequest = buildMyRequest();

const txId = await adapter.requestTransaction(
  Transaction.createCustomTransaction(
    adapter.address,   // the account that executes it
    recipientAddress,
    request,
    inputNoteIds,      // optional: notes the request consumes
    inputNoteBytes     // optional: Uint8Array[] of notes to import first
  )
);

try {
  const { txHash, outputNotes } = await adapter.waitForTransaction(txId);
  // outputNotes are SDK Note objects, for example a private note to hand on
} catch (error) {
  // WalletTransactionError: it failed or did not settle in time.
  // A refused request rejects with the provider's own error.
}

• requestTransaction also accepts Transaction.createSendTransaction(...) and createConsumeTransaction(...); the adapter routes those to the send and consume requests.
• CustomTransaction serializes the request in its constructor and Bread deserializes it with its own SDK, so build it with the same @miden-sdk/miden-sdk minor version Bread uses, 0.17.
• SendTransaction takes an optional sixth argument, recallBlocks.

Private notes

Send with noteType: 'private' and the note's details stay off chain. To pass a private note to Bread yourself, for example one your server holds for the user, import its serialized bytes:

const noteId = await adapter.importPrivateNote(noteBytes); // Uint8Array
const notes = await adapter.requestConsumableNotes();     // listed if this account can consume it

Sign bytes

signBytes asks the connected account to sign data you prepared with the Miden SDK. The user approves every signature.

import { Word } from '@miden-sdk/miden-sdk';

const signature = await adapter.signBytes(word.serialize(), 'word');
// or: adapter.signBytes(signingInputs.serialize(), 'signingInputs')
// signature: the SDK's serialized Signature bytes

To verify, take the word Bread signed and check publicKey.verify(word, Signature.deserialize(signature)). For a word, Blind, or Arbitrary payload, compute that word with domainSeparatedSignCommitment(data, kind) from @miden-sdk/miden-sdk 0.17.10; for a transaction summary it is signingInputs.toCommitment(). A page that calls the injected provider directly also gets the word back as signedCommitment. A word, Blind, or Arbitrary signature does not verify against the raw payload.

To sign people in, use the login key below instead: it is separate from the account's transaction keys.

Sign in with Bread

Each account has one login key per site. It comes from the account's root key and your registrable domain, so the same recovery phrase brings the same login back on every device and in every Bread app. It signs only sign-in messages, never transactions.

// After connecting. Not in the adapter or its types: call the provider directly.
const wallet = (window as any).midenWallet;

if (wallet?.requestLoginKey) {
  const { loginKey } = await wallet.requestLoginKey(); // 32 bytes, no prompt

  const word = await fetchChallengeWord();           // 32 bytes from your server
  const { signature } = await wallet.signLoginBytes(word, 'word'); // prompts

  await fetch('/login', {
    method: 'POST',
    body: JSON.stringify({ loginKey: toHex(loginKey), signature: toHex(signature) })
  });
}

import { Felt, FeltArray, Poseidon2, Word } from '@miden-sdk/miden-sdk';

// Bread signs M, never the word itself.
function loginMessage(word: Word) {
  const tag = new Uint8Array(16);
  tag.set(new TextEncoder().encode('Bread login v1'));
  const view = new DataView(tag.buffer);
  const tagElements = [0, 4, 8, 12].map(at => new Felt(BigInt(view.getUint32(at, true))));
  return Poseidon2.hashElements(new FeltArray([...tagElements, ...word.toFelts()]));
}

• Key: requestLoginKey() resolves to { loginKey }, the 32-byte commitment of the login key, in the same form as the publicKey a connection returns. It needs a connected session and shows no prompt.
• Signature: signLoginBytes(data, 'word') always asks for approval, on a screen that names your site. It resolves to { signature }, a 66-byte recoverable ECDSA signature over secp256k1 with Keccak: [0x01, r, s, v].
• Verify: on your server, compute the login message M from your own word. Bread never sends the public key and the SDK's PublicKey.recoverFrom supports only Falcon keys, so recover the secp256k1 key with an ECDSA library from r, s and v over keccak256 of M's 32 serialized bytes. Deserialize it as an SDK PublicKey (0x01 and the 33-byte compressed point), check publicKey.verify(M, signature), and accept only when publicKey.toCommitment() equals loginKey. Checking against the raw word fails by design.
• Domain: Bread takes the domain from your page's real origin, never from the request. app.example.com and www.example.com share one key. Pages must be https, except localhost and loopback addresses.

The mobile browser

On iOS and Android, Explore opens your dApp in Bread's own browser. The adapter works unchanged; a few details differ from the extension.

• Injected after load. window.midenWallet appears after each page load, not at document start. The adapter polls for it every second, so wait for readyState to be Installed instead of checking the global once at startup.
• Origin first. Bread refuses requests with NOT_GRANTED until it has confirmed your page's origin, which takes a moment after navigation.
• Dialogs, not windows. Approvals open in a dialog over your page. Requests time out in the page after five minutes.
• Toolbar space. In ordinary browser mode Bread adds padding-bottom: calc(96px + env(safe-area-inset-bottom, 0px)) !important to your body so content clears its bottom toolbar.
• Kept alive. A dApp the user leaves is parked, and picking it again restores the same page and JavaScript state without a reload. A repeat connect() repopulates the account.

Fullscreen

Games and immersive dApps can drop Bread's browser chrome on iOS and Android. Your page fills the display; a small translucent Bread capsule stays in the corner as the way back.

<head>
  <meta name="bread-display" content="fullscreen" />
  <meta name="bread-ready" content="manual" />
  <meta name="theme-color" content="#101010" />
</head>

// With bread-ready="manual", reveal once your first correctly sized frame is drawn.
await renderFirstFrame();
if (window.bread?.presentation) {
  // Rejects where Bread falls back to browser mode; the page then shows as usual.
  await window.bread.presentation.ready().catch(() => {});
}

// Leave fullscreen and close the page from your own UI.
quitButton.onclick = async () => {
  if (window.bread?.presentation) await window.bread.presentation.close();
};

/* Sit beside the capsule when the rectangle is known */
:root[data-bread-control-bounds='true'] .hud {
  top: var(--bread-control-top);
  height: var(--bread-control-height);
  margin-left: calc(var(--bread-control-left) + var(--bread-control-width) + 12px);
}

/* No rectangle, as on older hosts: reserve the whole top row */
:root:not([data-bread-control-bounds='true']) .hud {
  padding-top: var(--bread-control-inset-top, 0px);
}

/* Backgrounds may bleed; controls stay inside the safe area */
.controls {
  padding-bottom: var(--bread-safe-area-bottom, 0px);
  padding-left: var(--bread-safe-area-left, 0px);
  padding-right: var(--bread-safe-area-right, 0px);
}

Bread reads these tags while the head parses, so put them in your initial HTML rather than adding them from a bundle. The settings are fixed at DOMContentLoaded.

Layout anatomy

Pick a region to see what Bread reserves and which variable describes it. Every value is in CSS pixels, updated on rotation, resize and safe-area changes.

The same numbers are available to JavaScript, as frozen snapshots that change on every update:

function layout() {
  const state = window.__breadPresentationState;
  if (!state) return;
  const { controlBounds, safeAreaInsets } = state; // either may be missing on older hosts
  // controlBounds: { left, top, width, height }
  // safeAreaInsets: { top, left, right, bottom }
  resizeRenderer(controlBounds, safeAreaInsets);
}
document.addEventListener('breadpresentationchange', layout);
layout();

Lifecycle

1. PrepareBread shows your theme-color and waits up to 30 seconds of foreground time for readiness, then offers Retry and Back to Bread.
2. RevealAutomatic at DOMContentLoaded, or when you call presentation.ready().
3. MinimizeA tap on the capsule parks your page in Bread like any other app. Nothing reloads.
4. RestorePicking it again brings back the same document and session, still fullscreen.

• Motion: dApps open and minimize with a smooth morph, a native spring animation that runs at your display's full refresh rate, up to 120 Hz on ProMotion iPhones. Tap the Bread capsule to minimize, or grab the window mid-flight and the motion follows your finger and carries your velocity.
• Overlays: wallet confirmations, alerts and locking suspend your page; it resumes when the last overlay closes.
• Closing: users close a fullscreen page with Bread's usual parked-app controls; you can call presentation.close(). Closing rejects that page's pending wallet confirmation and drops its saved session. A transaction already submitted continues.
• Rotation: fullscreen opens in the current orientation and follows the device.
• Promises: ready() and close() resolve when the native side acknowledges and reject on refusal or after 30 seconds. At most 32 calls may be outstanding.

Google and Apple sign-in

Google and Apple refuse to sign in inside embedded web views. On phones, window.bread.auth.open(url) runs the flow in a secure system sheet while your page stays loaded.

const hex = bytes => Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
const verifier = hex(crypto.getRandomValues(new Uint8Array(32)));
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
const url = new URL('/auth/start', location.origin);
url.searchParams.set('challenge', hex(new Uint8Array(digest)));

if (window.bread?.auth) {
  const result = await window.bread.auth.open(url.href);
  const handle = !result.cancelled && new URL(result.url).searchParams.get('login');
  if (handle) {
    await fetch('/auth/redeem', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ handle, verifier })
    });
  }
}

<!doctype html>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- Serve with Cache-Control: no-store. Origin and handle are written by your server. -->
<meta http-equiv="refresh" content="0; url=com.miden.wallet.auth://callback?origin=https%3A%2F%2Fexample.org&amp;login=HANDLE" />
<title>Return to Bread</title>
<a href="com.miden.wallet.auth://callback?origin=https%3A%2F%2Fexample.org&amp;login=HANDLE">Return to Bread</a>

• Result: open resolves to a frozen { url }, the untouched callback URL, or { cancelled: true } when the user closes the sheet. It has no timeout.
• URL rules: the URL must be an absolute https URL on your page's own origin, up to 4096 characters. Inside the sheet the flow can redirect to Google or Apple as usual.
• Ending the flow: navigate to com.miden.wallet.auth://callback with exactly one origin parameter naming your page's origin. Bread reads nothing else from the URL, so every other parameter name is yours.
• One at a time: only one sheet can be open across Bread, and only while your page is visible and Bread is in the foreground.
• Platforms: iOS uses the system sign-in sheet, which shares Safari's cookies. Android uses an Auth Tab where the browser supports it, otherwise a Custom Tab.

Every URL and callback rule, character by character, is in the sign-in sheet reference.

Open links

Send people straight into your dApp inside Bread on their phone. Type an https address to build both link forms.

• Formats: https://bread.miden.xyz/open#url=<page> carries the page in the fragment, which browsers never send to the link host. com.miden.wallet://open?url=<page> is the app scheme.
• Rules: Bread opens only https pages, and never a page with a user name or password before the host.
• Prompt: Bread waits until the wallet is unlocked. A page whose origin is listed in Explore opens straight away; any other asks "Open host?" first.
• Mobile only: the desktop app and the extension do not handle open links.

Explore listing (optional)

Your dApp does not need to be listed. Any dApp connects to Bread and works in it without a listing, opened from its address, a link or the search box in Explore. The Explore catalog is only Bread's built-in discovery section.

To apply, open an issue on the wallet repository.

Test your dApp

Start on testnet in a desktop browser with the extension, then check the phone apps.

Get a test wallet

• Choose Testnet in Bread's Developer Settings before creating the wallet, then fund it from faucet.testnet.miden.io. Testnet's Explore also lists faucets.
• Follow your transactions on testnet.midenscan.com.

Open your build

• Extension: the provider is injected on http://localhost and http://127.0.0.1, so a local dev server works as is.
• Phones: type your address into Explore's search box. An address typed without a scheme gets https://, so write http:// yourself for a plain-http server.
• iOS loads plain-http pages. Android store builds allow no cleartext to your server, so expose your dev server over https, for example through a tunnel.
• Desktop: Explore accepts http and https addresses and opens them in Bread's dApp window, which the next address reuses.
• window.bread.auth needs an https page; the login key needs https or a loopback host such as localhost.

Gotchas

The ones that cost people an afternoon.

Under the hood

Native integration notes and specifications, for when you need every edge case.

Found something missing or wrong? Open an issue.