# @a16z/helios
Helios is a trustless, efficient, and portable Ethereum light client written in Rust with TypeScript bindings for web and Node.js environments. It comes both as a UMD and ES module.
## Installation & Basic Setup Examples
### 1. Installing using NPM
Install the package:
```bash
npm install @a16z/helios
```
Basic usage in your project (e.g., `index.js` or `index.mjs` or `main.ts`):
```typescript
import { createHeliosProvider } from '@a16z/helios';
async function main() {
// Create provider - WASM initialization is handled automatically
const heliosProvider = await createHeliosProvider({
executionRpc: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
consensusRpc: 'https://ethereum.operationsolarstorm.org',
network: 'mainnet',
checkpoint: "0x..."
}, 'ethereum');
await heliosProvider.waitSynced();
console.log('Helios is synced and ready!');
// Example: Get latest block number
const blockNumber = await heliosProvider.request({ method: 'eth_blockNumber', params: [] });
console.log('Latest block number:', parseInt(blockNumber, 16));
}
main().catch(console.error);
```
### 2. Loading on a webpage from a CDN
For a quick test, you can try Helios directly in an HTML file using a CDN like unpkg.
**As a UMD module:**
```html
Helios UMD Test
```
**As an ES module:**
```html
Helios ESM Test
```
## Usage as EIP-1193 provider
Helios can be used as an EIP-1193 provider. Once initialized and synced (as shown in the examples above), `heliosProvider` can be used with libraries like viem, ethers.js, web3.js, etc.
Example with viem:
```typescript
import { createPublicClient, custom } from 'viem';
import { mainnet } from 'viem/chains';
import { createHeliosProvider } from '@a16z/helios';
// Create and sync Helios provider
const heliosProvider = await createHeliosProvider({
executionRpc: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
consensusRpc: 'https://lodestar-mainnet.chainsafe.io',
network: 'mainnet',
checkpoint: "0x..."
}, 'ethereum');
await heliosProvider.waitSynced();
// Use with viem
const client = createPublicClient({
chain: mainnet,
transport: custom(heliosProvider)
});
const blockNumber = await client.getBlockNumber();
console.log('Latest block number:', blockNumber);
```
## Cleanup
If Helios is used as a transport for `ethers` or `viem`, calling `EthersProvider.destroy()` will NOT destroy underlying Helios instance nor will stop the background tasks.
For proper cleanup, call `shutdown()` (or its alias `destroy()`) on your Helios provider instance to properly release resources:
```typescript
// Clean up when done
await heliosProvider.shutdown();
```
This unsubscribes all active subscriptions, aborts background tasks, removes event listeners, and frees WASM memory. The method is idempotent—calling it multiple times is safe. After dereferencing Helios provider instance will be garbage collected.
## Documentation
See [helios github repo](https://github.com/a16z/helios/) for more details.
## License
This project is licensed under the MIT License - see the main repository for details.