# 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.

- **Package:** [`@vilna-io/storage-client`](https://www.npmjs.com/package/@vilna-io/storage-client)
- **License:** MIT
- **Environment:** Browser only (requires `window`)


## Installation


```bash
npm install @vilna-io/storage-client
```

## Quick start


```typescript
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](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) 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


```typescript
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


```typescript
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


```typescript
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


```typescript
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


```typescript
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:


```typescript
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 |



```typescript
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
  }
}
```

## Further reading

Vilna Widget
Browser extension overview and integration flow

TypeScript SDK
Official API client for server-side operations

Platform API
Complete endpoint documentation