Skip to content

Getting Started

This guide walks you through integrating the Dilithia Browser SDK into a dapp from scratch.

1. Install

npm install @dilithia/browser-sdk

2. Detect the Wallet

Before calling any wallet function, check that the Dilithia Wallet extension is installed:

import { hasDilithiaProvider } from "@dilithia/browser-sdk";

if (!hasDilithiaProvider()) {
  // Show an install prompt to the user
  console.error("Dilithia Wallet not detected. Please install the extension.");
  return;
}

Tip

Call hasDilithiaProvider() early -- for example, on page load -- so you can show an appropriate UI before the user tries to interact.

3. Connect

Request a connection. The wallet prompts the user for approval. Optionally pass the permissions your dapp needs:

import { connect } from "@dilithia/browser-sdk";

const session = await connect(["dilithia_signPayload"]);
console.log("Address:", session.address);
console.log("Chain:", session.chainId);
console.log("RPC URL:", session.rpcUrl);

The returned session object contains everything you need: the user's address, public key, chain info, granted permissions, and the RPC URL for creating a ChainClient.

4. Create a Chain Client

Use the rpcUrl from the session to create a ChainClient for read-only operations:

import { createChainClient } from "@dilithia/browser-sdk";

const chain = createChainClient(session.rpcUrl);

The ChainClient does not require a wallet -- it talks directly to the RPC node. You can also create one with a hardcoded URL:

const chain = createChainClient("https://rpc.dilithia.network/rpc");

5. Read Balance

const { balance } = await chain.getBalance(session.address);
console.log("Balance:", balance, "DILI");

6. Send a Transfer

Use the transfer() wallet function to send DILI tokens:

import { transfer } from "@dilithia/browser-sdk";

const tx = await transfer("dili1bob", 50);
console.log("Submitted:", tx.txHash);
console.log("Accepted:", tx.accepted);

The wallet handles nonce management, signing, and submission.

7. Wait for Receipt

Poll for the transaction receipt using the ChainClient:

const receipt = await chain.waitForReceipt(tx.txHash);

if (receipt.status === "success") {
  console.log("Confirmed at block", receipt.blockHeight);
  console.log("Gas used:", receipt.gasUsed);
  console.log("Fee paid:", receipt.feePaid, "DILI");
} else {
  console.error("Transaction failed:", receipt.error);
}

By default, waitForReceipt polls up to 30 times with 2-second intervals (60 seconds total). You can customize this:

// 60 attempts, 1 second apart = 60 seconds max
const receipt = await chain.waitForReceipt(tx.txHash, 60, 1000);

8. Handle Errors

The SDK throws standard JavaScript Error objects. Use try/catch to handle them:

Provider not found

try {
  const session = await connect();
} catch (err) {
  if (err.message.includes("provider not found")) {
    // Prompt user to install the extension
  }
}

User rejected the request

try {
  const session = await connect(["dilithia_signPayload"]);
} catch (err) {
  if (err.message.includes("denied") || err.message.includes("rejected")) {
    console.log("User rejected the connection request.");
  }
}

Transaction failed on-chain

const receipt = await chain.waitForReceipt(tx.txHash);
if (receipt.status !== "success") {
  console.error("Transaction failed:", receipt.error);
}

Receipt timeout

try {
  const receipt = await chain.waitForReceipt(tx.txHash, 10, 1000);
} catch (err) {
  if (err.message.includes("Receipt not found after")) {
    console.error("Transaction may still be pending. Check later with getReceipt().");
  }
}

Full Example

Putting it all together:

import {
  hasDilithiaProvider,
  connect,
  createChainClient,
  transfer,
  on,
} from "@dilithia/browser-sdk";

async function main() {
  if (!hasDilithiaProvider()) {
    document.getElementById("status")!.textContent = "Please install Dilithia Wallet.";
    return;
  }

  const session = await connect(["dilithia_signPayload"]);
  const chain = createChainClient(session.rpcUrl);

  // Listen for account changes
  on("accountsChanged", () => {
    console.log("Account changed -- refresh UI");
  });

  // Show balance
  const { balance } = await chain.getBalance(session.address);
  console.log(`${session.address} holds ${balance} DILI`);

  // Transfer
  const tx = await transfer("dili1bob", 25);
  const receipt = await chain.waitForReceipt(tx.txHash);
  console.log("Done:", receipt.status, "at block", receipt.blockHeight);
}

main().catch(console.error);

Next Steps