[Tutorial] DApp Connector API: Connecting a Browser dApp to Midnight Wallets

// src/hooks/wallet.constants.ts
export const COMPATIBLE_CONNECTOR_API_VERSION = '4.x';
export const NETWORK_ID = 'preprod';

// src/hooks/useWallet.ts
export function getCompatibleWallets(): InitialAPI[] {
  if (!window.midnight) return [];

  return Object.values(window.midnight).filter(
    (wallet): wallet is InitialAPI =>
      !!wallet &&
      typeof wallet === 'object' &&
      'apiVersion' in wallet &&
      semver.satisfies(wallet.apiVersion, COMPATIBLE_CONNECTOR_API_VERSION)
  );
}

// src/components/WalletSelectModal.tsx
function getWalletIcon(rdns: string | undefined): string | null {
  if (!rdns) return null;
  if (rdns.includes('lace')) return laceSvg;
  if (rdns.includes('1am') || rdns.includes('iam')) return iamSvg;
  return null;
}

export function WalletSelectModal({ isOpen, onClose, wallets, onSelect, connecting }: Props) {
  const [pending, setPending] = useState<InitialAPI | null>(null);
  if (!isOpen) return null;

  return (
    <div>
      <h3>Connect Wallet</h3>
      {wallets.map((w) => (
        <button
          key={w.rdns}
          onClick={() => {
            setPending(w);
            onSelect(w);
          }}
          disabled={connecting}
        >
          <img src={getWalletIcon(w.rdns) ?? fallback} />
          <span>{w.name}</span>
        </button>
      ))}
      {connecting && pending && <div>Connecting to {pending.name}...</div>}
      <Button onClick={onClose} disabled={connecting}>Cancel</Button>
    </div>
  );
}

// src/components/ConnectButton.tsx
export function ConnectButton() {
  const { isConnected, connect, setWallet, setShowAccountModal } = useWalletStore();
  const [wallets] = useState(() => getCompatibleWallets());
  const [showModal, setShowModal] = useState(false);

  const handleConnect = async (selectedWallet: InitialAPI) => {
    setWallet(selectedWallet);
    setShowModal(false);
    await connect('preprod');
  };

  const handleClick = () => {
    if (isConnected) {
      setShowAccountModal(true);
    } else if (wallets.length === 1) {
      handleConnect(wallets[0]);
    } else {
      setShowModal(true);
    }
  };

  return (
    <>
      <Button onClick={handleClick}>Connect Wallet</Button>
      <Modal isOpen={showModal} onClose={() => setShowModal(false)}>
        <WalletSelectModal
          isOpen={showModal}
          onClose={() => setShowModal(false)}
          wallets={wallets}
          onSelect={handleConnect}
          connecting={isConnecting}
        />
      </Modal>
    </>
  );
}

// src/hooks/useWallet.ts
connect: async (networkId = NETWORK_ID) => {
  const { wallet } = get();
  if (!wallet) {
    set({ error: 'No wallet selected' });
    return;
  }

  set({ isConnecting: true, error: null });

  try {
    const connectedApi = await wallet.connect(networkId);
    const status = await connectedApi.getConnectionStatus();

    if (status.status !== 'connected') {
      throw new Error(`Wallet status: ${status.status}`);
    }

    const config = await connectedApi.getConfiguration();
    const shielded = await connectedApi.getShieldedAddresses();
    const unshielded = await connectedApi.getUnshieldedAddress();
    const dustAddr = await connectedApi.getDustAddress();

    set({
      connectedApi,
      isConnected: true,
      config,
      addresses: {
        shieldedAddress: shielded.shieldedAddress,
        shieldedCoinPublicKey: shielded.shieldedCoinPublicKey,
        shieldedEncryptionPublicKey: shielded.shieldedEncryptionPublicKey,
        unshieldedAddress: unshielded.unshieldedAddress,
        dustAddress: dustAddr.dustAddress,
      },
      balances: {
        shielded: {},
        unshielded: {},
        dust: { balance: 0n, cap: 0n },
      },
    });

    localStorage.setItem('midnight_last_wallet', wallet.rdns);
  } catch (err) {
    set({
      error: err instanceof Error ? err.message : 'Connection failed',
      isConnected: false,
      connectedApi: null,
    });
  } finally {
    set({ isConnecting: false });
  }
},

// src/hooks/useWallet.ts
export async function tryAutoConnect(): Promise<void> {
  const lastRdns = localStorage.getItem('midnight_last_wallet');
  if (!lastRdns || !window.midnight) return;

  const wallets = getCompatibleWallets();
  const match = wallets.find((w) => w.rdns === lastRdns);
  if (!match) return;

  const store = useWalletStore.getState();
  store.setWallet(match);
  await store.connect();
}

// src/components/AccountModal.tsx
export function AccountModal() {
  const {
    showAccountModal, setShowAccountModal,
    addresses, balances, config,
    isLoadingState, loadWalletState,
    disconnect, wallet, error,
  } = useWalletStore();

  const [copiedKey, setCopiedKey] = useState<string | null>(null);

  const handleCopy = (key: string, address: string | undefined) => {
    if (!address) return;
    navigator.clipboard.writeText(address);
    setCopiedKey(key);
    setTimeout(() => setCopiedKey(null), 2000);
  };

  // Renders shielded/unshielded/dust balances,
  // copyable addresses, refresh button, disconnect
}

// src/hooks/useWalletSubscription.ts
export function useWalletSubscription(options = {}) {
  const { balanceInterval = 15000, connectionInterval = 5000 } = options;
  const { connectedApi, isConnected, loadWalletState, disconnect } = useWalletStore();
  const lastStatusRef = useRef<'connected' | 'disconnected'>('disconnected');

  // 1. Balance polling
  useEffect(() => {
    if (!isConnected || !connectedApi) return;
    loadWalletState();
    const id = setInterval(() => loadWalletState(), balanceInterval);
    return () => clearInterval(id);
  }, [isConnected, connectedApi, loadWalletState, balanceInterval]);

  // 2. Connection-status polling
  useEffect(() => {
    if (!isConnected || !connectedApi) return;

    const check = async () => {
      try {
        const status = await connectedApi.getConnectionStatus();
        lastStatusRef.current = status.status;
        if (status.status === 'disconnected') disconnect();
      } catch {
        if (lastStatusRef.current === 'connected') disconnect();
      }
    };

    const id = setInterval(check, connectionInterval);
    return () => clearInterval(id);
  }, [isConnected, connectedApi, disconnect, connectionInterval]);
}

// src/hooks/useWallet.ts
loadWalletState: async () => {
  const { connectedApi } = get();
  if (!connectedApi) return;

  set({ isLoadingState: true, error: null });

  try {
    const [shieldedBalances, unshieldedBalances, dustBalance] = await Promise.all([
      connectedApi.getShieldedBalances(),
      connectedApi.getUnshieldedBalances(),
      connectedApi.getDustBalance(),
    ]);

    set({
      balances: {
        shielded: shieldedBalances,
        unshielded: unshieldedBalances,
        dust: dustBalance,
      },
    });
  } catch (err) {
    set({ error: err instanceof Error ? err.message : 'Failed to load wallet state' });
  } finally {
    set({ isLoadingState: false });
  }
},

// src/lib/transaction-cli.ts
import * as Rx from 'rxjs';

export function subscribeToWalletSdkState(
  ctx: CliWalletContext,
  listener: (state: any) => void
): () => void {
  const sub = (ctx.wallet as any).state().subscribe(listener);
  return () => sub.unsubscribe();
}

export async function waitForWalletSync(ctx: CliWalletContext): Promise<any> {
  return Rx.firstValueFrom(
    (ctx.wallet as any)
      .state()
      .pipe(Rx.filter((s: any) => s.isSynced))
  );
}

// scripts/test-subscription.ts
const ctx = await restoreWalletState(MNEMONIC);

// 1. Block until fully synced
await waitForWalletSync(ctx);

// 2. Subscribe to push updates
const unsubscribe = subscribeToWalletSdkState(ctx, (state: any) => {
  if (!state.isSynced) return;

  const shielded = state.shielded?.balances ?? {};
  const unshielded = state.unshielded?.balances ?? {};
  const dust = state.dust?.balance(new Date()) ?? 0n;

  console.log('Shielded:', Object.entries(shielded)
    .map(([k, v]) => `${k.slice(0, 8)}..=${v?.toString()}`).join(', ') || '(empty)');
  console.log('Unshielded:', Object.entries(unshielded)
    .map(([k, v]) => `${k.slice(0, 8)}..=${v?.toString()}`).join(', ') || '(empty)');
  console.log('Dust:', dust.toString());
});

// src/pages/Transfer.tsx
const handleTransfer = useCallback(async () => {
  if (!connectedApi) {
    setError('Wallet not connected');
    return;
  }

  try {
    const value = BigInt(Math.round(Number(amount) * 1_000_000));

    // 1. Decode Bech32 address to raw hex bytes
    const parsed = MidnightBech32m.parse(recipient);
    const unshieldedAddr = parsed.decode(UnshieldedAddress, 'preprod');
    const hexRecipient = unshieldedAddr.data.toString('hex');

    // 2. Build an unproven transaction blueprint manually
    const unshieldedOffer = UnshieldedOffer.new(
      [], // inputs — wallet selects these
      [{ value, owner: hexRecipient, type: nativeToken().raw }],
      [] // signatures — wallet adds these
    );

    const intent = Intent.new(new Date(Date.now() + 30 * 60 * 1000));
    (intent as any).fallibleUnshieldedOffer = unshieldedOffer;

    const unsealedTx = Transaction.fromParts('preprod', undefined, undefined, intent as any);

    // 3. Prove the transaction (PreProof → Proof)
    const zkConfigProvider = new FetchZkConfigProvider(window.location.origin);
    const provingProvider = await connectedApi.getProvingProvider(zkConfigProvider);
    const provenTx = await unsealedTx.prove(provingProvider, CostModel.initialCostModel());

    const serializedTx = toHex(provenTx.serialize());

    // 4. Wallet balances, signs, and pays fees
    const result = await connectedApi.balanceUnsealedTransaction(serializedTx, { payFees: true });

    // 5. Submit
    await connectedApi.submitTransaction(result.tx);

    setTxId(result.tx.slice(0, 64));
    loadWalletState();
  } catch (err) {
    setError(err instanceof Error ? err.message : String(err));
  }
}, [connectedApi, recipient, amount, loadWalletState]);

const parsed = MidnightBech32m.parse(recipient);
const unshieldedAddr = parsed.decode(UnshieldedAddress, 'preprod');
const hexRecipient = unshieldedAddr.data.toString('hex');

BALANCE_FAILED: invalid network ID - expect 'preprod' found 'undeployed'

expected header tag '...proof...', got '...proof-preimage...'

// src/lib/transaction-cli.ts
const seed = Buffer.from(await bip39.mnemonicToSeed(mnemonic));
const hdWallet = HDWallet.fromSeed(seed);

const derivationResult = hdWallet.hdWallet
  .selectAccount(0)
  .selectRoles([Roles.Zswap, Roles.NightExternal, Roles.Dust])
  .deriveKeysAt(0);

hdWallet.hdWallet.clear(); // Security: wipe seed from memory

const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(derivationResult.keys[Roles.Zswap]);
const dustSecretKey = ledger.DustSecretKey.fromSeed(derivationResult.keys[Roles.Dust]);
const unshieldedKeystore = createKeystore(derivationResult.keys[Roles.NightExternal], 'preprod');

// src/lib/transaction-cli.ts
const baseConfig: any = {
  networkId: 'preprod',
  indexerClientConnection: {
    indexerHttpUrl: 'https://indexer.preprod.midnight.network/api/v4/graphql',
    indexerWsUrl: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
  },
  relayURL: new URL('wss://rpc.preprod.midnight.network'),
  provingServerUrl: new URL('http://localhost:6300'),
  costParameters: { additionalFeeOverhead: 300_000_000_000_000n, feeBlocksMargin: 5 },
  txHistoryStorage: new InMemoryTransactionHistoryStorage(),
  batchUpdates: { size: 500, timeout: 50, spacing: 0 },
};

const wallet: any = await (WalletFacade as any).init({
  configuration: baseConfig,
  shielded: (cfg: any) => ShieldedWallet(cfg).startWithSecretKeys(shieldedSecretKeys),
  unshielded: (cfg: any) =>
    UnshieldedWallet({ ...cfg, txHistoryStorage: new InMemoryTransactionHistoryStorage() })
      .startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
  dust: (cfg: any) =>
    DustWallet(cfg).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
});

await wallet.start(shieldedSecretKeys, dustSecretKey);

// scripts/test-v3-sync-and-transfer.ts
import { unshieldedToken } from '@midnight-ntwrk/ledger-v8';

const recipe = await ctx.wallet.transferTransaction(
  [
    {
      type: 'unshielded',
      outputs: [
        {
          amount: 1n,
          receiverAddress: ctx.unshieldedKeystore.getBech32Address(),
          type: unshieldedToken().raw,
        },
      ],
    },
  ],
  { shieldedSecretKeys: ctx.shieldedSecretKeys, dustSecretKey: ctx.dustSecretKey },
  { ttl: new Date(Date.now() + 30 * 60 * 1000) }
);

const signedRecipe = await ctx.wallet.signRecipe(
  recipe,
  (payload: Uint8Array) => ctx.unshieldedKeystore.signData(payload)
);

const finalized = await ctx.wallet.finalizeRecipe(signedRecipe);
const txId = await ctx.wallet.submitTransaction(finalized);

// scripts/test-v3-sync-and-transfer.ts
const syncedState = await Rx.firstValueFrom(
  ctx.wallet.state().pipe(
    Rx.throttleTime(5_000),
    Rx.tap((s: any) => {
      // ...log progress...
    }),
    Rx.filter((s: any) => s.isSynced === true),
    Rx.timeout(120 * 60 * 1000), // 2 hours for first-time dust sync
  )
);

const saveBeforeExit = async () => {
  console.log('\n[Test] Interrupted — saving partial state...');
  await saveWalletState(ctx, '.wallet-state');
  await ctx.wallet.stop();
  process.exit(0);
};
process.on('SIGINT', saveBeforeExit);
process.on('SIGTERM', saveBeforeExit);

MNEMONIC="word1 word2 ... word24" npx tsx scripts/test-v3-sync-and-transfer.ts