IBExWalletAPI
Chains

Multichain Guide

IBEX FI API – Multichain Derivation & RPC Guide

This document explains how IBEx.Fi derives public addresses across multiple blockchain families and which RPC interfaces are needed for read/write operations.

The guide is implementation‑agnostic and focuses on: (1) how addresses are obtained, (2) what RPC endpoints you need to query balances and broadcast transactions, and (3) integration notes per chain family.

1) Derivation model (summary)

  • PRF first: When available, WebAuthn PRF (aka hmac‑secret) yields a deterministic 32‑byte master per credential. No private key is ever exposed.
  • Sealed fallback: If PRF is unavailable, a random 32‑byte master is generated once, sealed at rest (AES‑GCM), and unlocked in RAM after a successful passkey authentication.
  • Family separation: Each family uses HKDF with a distinct info label (e.g., evm:global, bitcoin:global, solana:global, cosmos:<hrp>``, …) to derive independent keys.
  • Exposure:
    • Sign‑up returns the full set of derived public addresses (eoaAddresses).
    • Sign‑in returns a filtered set controlled by WALLET_TYPE_SIGNIN (CSV of types).

Supported families (current): EVM, Bitcoin (P2WPKH, P2TR), Solana, Cosmos, Polkadot, Tezos (tz1/tz2/tz3), Near, Stellar, Cardano.

2) Runtime outputs

API responses include:

  • eoaAddress: EVM address (compat).
  • prfCapable: whether PRF was used for this credential.
  • eoaAddresses: array of \{ type, address \} entries, where type ∈ { EVM, SOLANA, BITCOIN_P2WPKH, BITCOIN_P2TR, COSMOS, POLKADOT, TEZOS_TZ1, TEZOS_TZ2, TEZOS_TZ3, NEAR, STELLAR, CARDANO }.

3) Chain families – RPC requirements

Below is a concise “what you need to talk to the chain” for reads (balance, UTXOs, state) and writes (broadcast signed payloads). Libraries are suggestions; you can use equivalents.

3.1 EVM (Ethereum and EVM‑compatible)

  • Address: secp256k1 EOA. Same address across all EVM chains.
  • Read RPC (JSON‑RPC):
    • eth_getBalance, eth_call, eth_getLogs, eth_getTransactionReceipt, etc.
    • Endpoint: any EVM JSON‑RPC (HTTPS). In IBEx, we proxy per chain via WEB3_URL/<chainId>/rpc.
  • Write RPC:
    • eth_sendRawTransaction (EOA flow) or ERC‑4337 bundler endpoints if using account abstraction.
    • Bundler/Paymaster (optional): POST /rpc/bundler, POST /rpc/paymaster (IBEx proxy), or direct provider.
  • Notes:
    • Gas pricing/1559 parameters required when locally signing EOA txs.
    • If you use Safe 4337, you’ll form UserOperations instead of raw legacy txs.

3.2 Bitcoin (UTXO)

  • Addresses:
    • P2WPKH bech32 (v0): bc1q... (testnet tb1q...).
    • P2TR Taproot bech32m (v1): bc1p... (testnet tb1p...).
  • Read RPC options:
    • Bitcoin Core JSON‑RPC: listunspent, gettxout, estimatesmartfee, getrawtransaction.
    • Or Esplora REST / Electrum for UTXO discovery and mempool/broadcast.
  • Write RPC:
    • Build PSBT (bitcoinjs / @scure/btc‑signer), sign (ECDSA or BIP340 Schnorr for Taproot), finalize, then:
    • Bitcoin Core: sendrawtransaction or Esplora POST /tx.
  • Notes:
    • Fee estimation: estimatesmartfee or external estimator.
    • Always handle change outputs and RBF/CPFP policy.

3.3 Solana

  • Address: ed25519 base58.
  • Read RPC (JSON‑RPC): getBalance, getAccountInfo, getProgramAccounts, etc.
  • Write RPC: sendTransaction (base64 encoded signed tx). Requires recentBlockhash, fee payer, and compiled message.
  • Endpoint: any Solana JSON‑RPC (HTTPS). Public RPCs or private providers.

3.4 Cosmos (Cosmos SDK chains)

  • Address: secp256k1 bech32 with chain HRP (e.g., cosmos1..., osmo1...).
  • Read RPC:
    • LCD REST: /cosmos/bank/v1beta1/balances/\{address\} etc.
    • Tendermint RPC: /abci_query, /status.
  • Write RPC:
    • Build proto/amino Tx, sign with secp256k1, broadcast via /cosmos/tx/v1beta1/txs (broadcast_mode/mode = sync|async|block).
    • Inputs required: chain‑id, accountNumber, sequence, gasPrice.
  • Endpoint: LCD (REST) + Tendermint (RPC) or gRPC gateways.

3.5 Polkadot/Substrate

  • Address: SS58 (ed25519 in our default; sr25519 also common).
  • Read RPC: Substrate JSON‑RPC (WebSocket strongly recommended) via Polkadot.js API (state queries, storage maps).
  • Write RPC: signed extrinsics submitted over WS RPC (author_submitExtrinsic).
  • Endpoint: chain’s WS endpoint (e.g., wss://...).

3.6 Tezos

  • Addresses:
    • tz1 (ed25519), tz2 (secp256k1), tz3 (p256). We derive all three; tz1 is the default most wallets use.
  • Read RPC: node RPC (e.g., /chains/main/blocks/head/context/contracts/\{address\}) or indexers (TzKT).
  • Write RPC: forge operation (manager ops), sign, inject via /injection/operation.
  • Endpoint: node RPC or indexer for reads; node RPC for writes.

3.7 Near

  • Address: ed25519 implicit account (hex of pubkey) or named accounts (not derived by us).
  • Read RPC: JSON‑RPC query (view methods, account state).
  • Write RPC: broadcast_tx_commit / broadcast_tx_async with signed transaction (requires nonce, recent block hash).
  • Endpoint: Near JSON‑RPC.

3.8 Stellar

  • Address: StrKey G... (ed25519 public key).
  • Read RPC: Horizon REST (/accounts/\{addr\}, /effects, /payments).
  • Write RPC: submit signed XDR via POST /transactions.
  • Endpoint: Horizon server for the target network.

3.9 Cardano

  • Address: bech32 addr1... (enterprise address in our baseline).
  • Read RPC: Ogmios/Kupo or indexers (Blockfrost REST). UTXO model similar to Bitcoin but different serialization.
  • Write RPC: build CBOR tx (cardano‑serialization‑lib), sign, submit via node (submitTx) or Blockfrost /tx/submit.
  • Endpoint: Cardano node service or Blockfrost.

4) Safe (contract wallets) vs EOA

  • Safe per chain: Safe (Gnosis Safe) is a smart account deployed per chain. IBEx exposes:
    • primarySafeAddress: Safe on the effective chain (header/query or default).
    • safeAddresses/safeAddress: list/mapping of Safes across chains (when multichain is requested).
  • EOA per family: A deterministic EOA/public address is computed for each family and exposed via eoaAddresses. For EVM, this can be used directly for raw EOA flows (or to control a Safe depending on your setup).

5) Operational checklist per family

  • EVM
    • JSON‑RPC URL (HTTPS).
    • Decide between EOA raw txs vs ERC‑4337 (bundler/paymaster).
    • Gas policy, nonce management.
  • Bitcoin
    • UTXO provider (Core, Esplora, Electrum) + fee estimator.
    • PSBT build/sign/finalize + broadcast.
  • Solana
    • JSON‑RPC URL.
    • Fetch recent blockhash; compile & sign message; sendTransaction.
  • Cosmos
    • LCD/Tendermint endpoints; chain‑id.
    • Account sequence, gas price, broadcast endpoint.
  • Polkadot
    • WS RPC; metadata chain; signed extrinsics.
  • Tezos
    • Node RPC; forge manager operations; inject.
  • Near
    • JSON‑RPC; get nonce & recent block hash; broadcast mode.
  • Stellar
    • Horizon base URL; build XDR; submit.
  • Cardano
    • Node or Blockfrost; CBOR tx build; submit.

6) Security notes

  • Keys never persist in plaintext at rest on the server; PRF or sealed fallback only.
  • Derivations per family use distinct HKDF info labels to avoid cross‑family key reuse.
  • Rate limiting, audit logs, and short‑lived in‑RAM usage are recommended for any server‑side signing flows.

7) Environment & filtering

  • WALLET_TYPE_SIGNIN (CSV) controls which \{ type, address \} entries are exposed at sign‑in (no effect on sign‑up).
  • EVM chain routing in IBEx is based on WEB3_URL/<chainId>/rpc (plus optional bundler/paymaster proxies).

If you need concrete code samples (build/sign/broadcast) per family, reach out; we can provide minimal examples using the libraries listed above.

Previous

Maintenance Mode

Next

Bitcoin Integration

On this page