Storage client

The @vilna-io/storage-client npm package connects web applications to the Vilna Storage browser extension for wallet operations such as network queries, address validation, and transaction signing. The browser extension it connects to is in development and not yet available to customers.

Package: @vilna-io/storage-client
License: MIT
Environment: Browser only (requires window)

Installation

npm install @vilna-io/storage-client

Quick start

import { connect } from "@vilna-io/storage-client";

const client = await connect();

const networks = await client.getSupportedNetworks();
// ['eip155:1', 'eip155:56', 'tron:728126428', ...]

The connect() function creates a client, detects the extension, and returns a ready-to-use instance. If the extension is not installed it throws VilnaStorageNotFoundError.

Core methods

Method	Returns	Description
`connect()`	`Promise<VilnaStorageClient>`	Create and connect a client in one step
`client.getSupportedNetworks()`	`Promise<string[]>`	List supported chain IDs in CAIP-2 format
`client.isAvailableAddress(params)`	`Promise<boolean>`	Check if an address exists in the wallet
`client.sendTransaction(params)`	`Promise<{ transactionId: string }>`	Open extension popup for signing
`client.isConnected()`	`boolean`	Check connection status
`client.on(event, handler)`	`this`	Subscribe to extension events
`client.removeListener(event, handler)`	`this`	Unsubscribe from events
`client.disconnect()`	`void`	Disconnect and clean up

Checking address availability

const isAvailable = await client.isAvailableAddress({
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
  derivationPath: "m/44'/60'/0'/0/0",
});

if (isAvailable) {
  // Address exists in the connected wallet
}

Sending transactions

The sendTransaction method opens the extension popup where the user reviews and confirms the transaction.

EVM transaction

const result = await client.sendTransaction({
  chainId: "eip155:1",
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
  derivationPath: "m/44'/60'/0'/0/0",
  transaction: {
    to: "0xRecipientAddress",
    value: "1000000000000000000", // 1 ETH in Wei
    tokenType: "native",
  },
});

console.log("Transaction ID:", result.transactionId);

EVM token transfer

const result = await client.sendTransaction({
  chainId: "eip155:1",
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
  derivationPath: "m/44'/60'/0'/0/0",
  transaction: {
    tokenType: "usdt",
    tokenAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    tokenAmount: "1000000", // 1 USDT (6 decimals)
    to: "0xRecipientAddress",
  },
});

TRON transaction

const result = await client.sendTransaction({
  chainId: "tron:728126428",
  address: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
  derivationPath: "m/44'/195'/0'/0/0",
  transaction: {
    to_address: "TRecipientAddress",
    amount: 1000000, // 1 TRX in Sun
    tokenType: "native",
  },
});

Event handling

client.on("accountsChanged", (accounts) => {
  console.log("Accounts changed:", accounts);
});

client.on("chainChanged", (chainId) => {
  console.log("Chain changed:", chainId);
});

Supported networks

Network	Chain ID
Ethereum Mainnet	`eip155:1`
Ethereum Sepolia	`eip155:11155111`
BNB Smart Chain	`eip155:56`
BNB Testnet	`eip155:97`
TRON Mainnet	`tron:728126428`
TRON Shasta	`tron:2494104990`

Call client.getSupportedNetworks() at runtime for the current list.

Utility functions

The package exports several utility namespaces for common validation tasks:

import { validationUtils, envUtils } from "@vilna-io/storage-client";

// Validate a CAIP-2 chain ID
validationUtils.isValidChainId("eip155:1"); // true

// Validate address formats
validationUtils.isValidEthereumAddress("0x742d35Cc6634C0532925a3b844Bc9e7595f7B123"); // true
validationUtils.isValidTronAddress("TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH"); // true

// Validate BIP-32 derivation path
validationUtils.isValidDerivationPath("m/44'/60'/0'/0/0"); // true

// Check if running in browser
envUtils.isBrowser(); // true/false

// Check if extension is installed
envUtils.isVilnaStorageAvailable(); // true/false

// Wait for extension to load (with timeout)
await envUtils.waitForVilnaStorage(5000);

Error handling

The package defines three error classes:

Error	Code	When
`VilnaStorageNotFoundError`	`EXTENSION_NOT_FOUND`	Extension is not installed
`VilnaStorageConnectionError`	`CONNECTION_ERROR`	Extension detected but connection failed
`VilnaStorageError`	varies	Base class for all storage errors

import {
  connect,
  VilnaStorageNotFoundError,
  VilnaStorageConnectionError,
} from "@vilna-io/storage-client";

try {
  const client = await connect();
} catch (err) {
  if (err instanceof VilnaStorageNotFoundError) {
    // Prompt user to install the extension
  } else if (err instanceof VilnaStorageConnectionError) {
    // Extension found but not responding
  }
}