# 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`](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