Skip to content

Commit 4efd5d6

Browse files
ncitronncitron
authored
feat: add TypeScript example application (#644)
This commit adds a complete TypeScript example application that demonstrates how to use the Helios light client to monitor multiple blockchain networks simultaneously. Features: - Real-time block monitoring for Ethereum, OP Mainnet, Base, and Linea - TypeScript implementation using Viem for modern Ethereum interactions - Vite-based development setup for fast iteration - Visual animations when new blocks are detected - Environment-based configuration for API keys - Complete documentation and setup instructions Technical implementation: - Uses helios-ts package from parent directory - Implements Helios as a custom transport provider for Viem - Polls each network every second for new blocks - Displays block number, timestamp, and transaction count - Handles errors gracefully with visual feedback - Updates lib.ts to reference Viem compatibility in documentation The example serves as a reference implementation for developers who want to integrate Helios into their TypeScript applications using modern tools.
1 parent 12210ee commit 4efd5d6

File tree

12 files changed

+1810
-16
lines changed

12 files changed

+1810
-16
lines changed

‎helios-ts/README.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,11 +99,12 @@ For a quick test, you can try Helios directly in an HTML file using a CDN like u
9999

100100
## Usage as EIP-1193 provider
101101

102-
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 ethers.js, web3.js, etc.
102+
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.
103103

104-
Example with ethers.js:
104+
Example with viem:
105105
```typescript
106-
import { ethers } from 'ethers';
106+
import { createPublicClient, custom } from 'viem';
107+
import { mainnet } from 'viem/chains';
107108
import { createHeliosProvider } from '@a16z/helios';
108109

109110
// Create and sync Helios provider
@@ -116,9 +117,13 @@ const heliosProvider = await createHeliosProvider({
116117

117118
await heliosProvider.waitSynced();
118119

119-
// Use with ethers.js
120-
const ethersProvider = new ethers.providers.Web3Provider(heliosProvider);
121-
const blockNumber = await ethersProvider.getBlockNumber();
120+
// Use with viem
121+
const client = createPublicClient({
122+
chain: mainnet,
123+
transport: custom(heliosProvider)
124+
});
125+
126+
const blockNumber = await client.getBlockNumber();
122127
console.log('Latest block number:', blockNumber);
123128
```
124129

‎helios-ts/example/.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Alchemy API Key
2+
# Get your key at https://www.alchemy.com/
3+
VITE_ALCHEMY_KEY=your_alchemy_key_here

‎helios-ts/example/.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Environment variables
5+
.env
6+
.env.local
7+
.env.*.local
8+
9+
# Build output
10+
dist/
11+
build/
12+
13+
# IDE
14+
.vscode/
15+
.idea/
16+
*.swp
17+
*.swo
18+
19+
# OS
20+
.DS_Store
21+
Thumbs.db
22+
23+
# Logs
24+
*.log
25+
npm-debug.log*
26+
yarn-debug.log*
27+
yarn-error.log*

‎helios-ts/example/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Helios TypeScript Example
2+
3+
This is a TypeScript implementation of the Helios multichain light client demo that displays the latest blocks from multiple chains.
4+
5+
## Prerequisites
6+
7+
Before running this example, you need to build the parent helios-ts library:
8+
9+
```bash
10+
cd ..
11+
npm install
12+
npm run build
13+
```
14+
15+
## Setup
16+
17+
1. Create a `.env` file by copying the example:
18+
```bash
19+
cp .env.example .env
20+
```
21+
22+
2. Edit `.env` and add your Alchemy API key:
23+
```
24+
VITE_ALCHEMY_KEY=your_actual_alchemy_key_here
25+
```
26+
27+
You can get an Alchemy API key at https://www.alchemy.com/
28+
29+
3. Install dependencies:
30+
```bash
31+
npm install
32+
```
33+
34+
## Development
35+
36+
Run the development server:
37+
```bash
38+
npm run dev
39+
```
40+
41+
The application will be available at http://localhost:3000
42+
43+
## Build
44+
45+
To build for production:
46+
```bash
47+
npm run build
48+
```
49+
50+
The built files will be in the `dist` directory.
51+
52+
## Features
53+
54+
- TypeScript for type safety
55+
- Viem for modern, lightweight Ethereum interactions
56+
- Vite for fast development and optimized builds
57+
- Real-time block updates from multiple chains:
58+
- Ethereum
59+
- OP Mainnet
60+
- Base
61+
- Linea
62+
63+
## How it works
64+
65+
The application uses the Helios light client as a custom transport provider for Viem. This creates a secure, verifiable connection to multiple blockchain networks. The app displays the latest block information for each chain, polling for new blocks every second and updating the display with animations when new blocks are found.
66+
67+
## Tech Stack
68+
69+
- **Helios**: Light client for secure blockchain connections
70+
- **Viem**: Modern TypeScript library for Ethereum interactions
71+
- **Vite**: Build tool and dev server
72+
- **TypeScript**: Type-safe development

‎helios-ts/example/index.html‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Helios TypeScript Demo – Latest Blocks</title>
7+
8+
<style>
9+
/* ---------- Layout ---------- */
10+
html,
11+
body {
12+
height: 100%;
13+
margin: 0;
14+
}
15+
body {
16+
font-family: Arial, Helvetica, sans-serif;
17+
display: flex;
18+
flex-direction: column;
19+
color: #333;
20+
}
21+
22+
h1,
23+
h2 {
24+
color: #ff8800;
25+
margin: 0 0 0.3rem 0;
26+
}
27+
.header {
28+
padding: 10px 25px;
29+
}
30+
31+
/* ---------- Panel grid ---------- */
32+
.panels-container {
33+
flex: 1 1 auto;
34+
display: grid;
35+
grid-template-columns: repeat(2, 1fr);
36+
gap: 20px;
37+
padding: 0 20px 20px;
38+
box-sizing: border-box;
39+
}
40+
@media (max-width: 900px) {
41+
.panels-container {
42+
grid-template-columns: 1fr;
43+
}
44+
}
45+
46+
/* ---------- Card ---------- */
47+
.panel {
48+
border: 1px solid #ddd;
49+
border-radius: 6px;
50+
padding: 24px;
51+
display: flex;
52+
flex-direction: column;
53+
background: #fafafa;
54+
min-height: 260px;
55+
}
56+
57+
/* ---------- Block read‑out ---------- */
58+
.block-info {
59+
position: relative;
60+
overflow: hidden;
61+
background: #f4f4f4;
62+
border-radius: 6px;
63+
font-size: 22px;
64+
line-height: 1.4;
65+
padding: 20px 18px;
66+
margin: 0;
67+
flex: 1 1 auto;
68+
display: flex;
69+
flex-direction: column;
70+
justify-content: center;
71+
align-items: center;
72+
text-align: center;
73+
white-space: pre-line;
74+
}
75+
.block-number {
76+
color: #ff8800;
77+
font-weight: 700;
78+
font-size: 1.8em;
79+
}
80+
81+
/* ---------- Loading wheel ---------- */
82+
.loading:before {
83+
content: "";
84+
width: 32px;
85+
height: 32px;
86+
border: 4px solid #ff8800;
87+
border-top-color: transparent;
88+
border-radius: 50%;
89+
animation: spin 1s linear infinite;
90+
}
91+
@keyframes spin {
92+
to {
93+
transform: rotate(360deg);
94+
}
95+
}
96+
97+
/* ---------- Loading bar (bottom, 12 px) ---------- */
98+
.block-info.animate::after {
99+
content: "";
100+
position: absolute;
101+
left: 0;
102+
bottom: 0;
103+
width: 100%;
104+
height: 12px;
105+
background: #ff8800;
106+
opacity: 0.6;
107+
transform-origin: left;
108+
transform: scaleX(0);
109+
animation: loadBar var(--duration, 2s) linear forwards;
110+
pointer-events: none;
111+
}
112+
@keyframes loadBar {
113+
to {
114+
transform: scaleX(1);
115+
}
116+
}
117+
118+
/* ---------- Opacity flash on update ---------- */
119+
.block-info.flash {
120+
animation: flashOpacity 0.8s ease-out;
121+
}
122+
@keyframes flashOpacity {
123+
0% {
124+
opacity: 0.25;
125+
}
126+
100% {
127+
opacity: 1;
128+
}
129+
}
130+
</style>
131+
</head>
132+
<body>
133+
<!-- ---------- Header ---------- -->
134+
<div class="header">
135+
<h1>Helios TypeScript Demo</h1>
136+
<p><em>Fast, secure &amp; portable multichain light client</em></p>
137+
</div>
138+
139+
<!-- ---------- Panels ---------- -->
140+
<div class="panels-container">
141+
<div class="panel">
142+
<h2>Ethereum</h2>
143+
<pre class="block-info loading" id="ethereum-latest"></pre>
144+
</div>
145+
<div class="panel">
146+
<h2>OP Mainnet</h2>
147+
<pre class="block-info loading" id="op-mainnet-latest"></pre>
148+
</div>
149+
<div class="panel">
150+
<h2>Base</h2>
151+
<pre class="block-info loading" id="base-latest"></pre>
152+
</div>
153+
<div class="panel">
154+
<h2>Linea</h2>
155+
<pre class="block-info loading" id="linea-latest"></pre>
156+
</div>
157+
</div>
158+
159+
<!-- ---------- Script ---------- -->
160+
<script type="module" src="/src/main.ts"></script>
161+
</body>
162+
</html>

0 commit comments

Comments
 (0)