Skip to content

Import sei-js docs #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexander-sei wants to merge 4 commits into
base: main
Choose a base branch
from
+378 −181
Open

Import sei-js docs #486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3c0c262
Add create-sei, add seijs index
alexander-sei Feb 26, 2026
7e739c2
Merge branch 'main' into sei-js-docs
alexander-sei Feb 26, 2026
3b14f64
split up ledger tutorial
alexander-sei Mar 14, 2026
6b4a891
Merge branch 'main' into sei-js-docs
alexander-sei Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 2 additions & 21 deletions content/evm/_meta.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,26 +56,7 @@ export default {
type: 'separator',
title: 'sei-js Library'
},
'seijs-introduction': {
title: 'Introduction to sei-js',
href: 'https://sei-js.docs.sei.io/introduction'
},
'scaffold-sei': {
title: 'Scaffold Sei',
href: 'https://sei-js.docs.sei.io/create-sei/welcome'
},
'mcp-server-seijs': {
title: 'MCP Server',
href: 'https://sei-js.docs.sei.io/mcp-server/introduction'
},
'sei-x402': {
title: 'X402',
href: 'https://sei-js.docs.sei.io/x402/introduction'
},
'seijs-ledger': {
title: 'Ledger',
href: 'https://sei-js.docs.sei.io/ledger/introduction'
},
'sei-js': '@sei-js SDK',

'-- Ecosystem Tutorials': {
type: 'separator',
Expand Down Expand Up @@ -104,5 +85,5 @@ export default {
type: 'separator',
title: 'Hardware Wallets'
},
'ledger-ethers': 'Using Ledger with Ethers'
'ledger-ethers': 'Ledger Setup (EVM)'
};
197 changes: 37 additions & 160 deletions content/evm/ledger-ethers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,200 +1,77 @@
---
title: "Using Ledger Wallet with Ethers on Sei"
description: "Learn how to integrate Ledger hardware wallets with the ethers.js library for secure Sei EVM transactions, including wallet setup, connection, and transaction signing."
keywords: ["ledger wallet", "ethers.js", "hardware wallet", "blockchain security", "sei transactions"]
title: 'Ledger Setup (EVM)'
description: 'Set up your Ledger hardware wallet for signing EVM transactions on Sei, including device configuration, Ethers.js integration, and a simple transfer example.'
keywords: ['ledger wallet', 'ethers.js', 'hardware wallet', 'blockchain security', 'sei transactions', 'evm']
---
# Using Ledger wallet with ethers on Sei

## Prerequisites & Setup
import { Callout } from 'nextra/components';

# Ledger Setup (EVM)

This guide covers connecting a Ledger hardware wallet to Sei's EVM for signing transactions with Ethers.js. For Cosmos-side signing with the `@sei-js/ledger` package, see the [@sei-js/ledger reference](/evm/sei-js/ledger).

## Prerequisites

1. **Ledger App Installation**

- On your Ledger device, open the Manager in Ledger Live and install **either** the **Sei** app **or** the **Ethereum** app.
- The Ethereum app on Ledger supports any EVM chain (like Sei), but the native Sei app may provide optimal compatibility.
On your Ledger device, open the Manager in Ledger Live and install **either** the **Sei** app **or** the **Ethereum** app. The Ethereum app supports any EVM chain (like Sei), but the native Sei app may provide optimal compatibility.

2. **Enable Blind Signing**

- Still in the Ledger device's Ethereum or Sei app settings, **enable "Blind signing"**.
- This permits the device to sign arbitrary EVM transactions and contract calls (e.g. precompiles), which would otherwise be rejected for safety.
In the Ledger device's Ethereum or Sei app settings, **enable "Blind signing"**. This permits the device to sign arbitrary EVM transactions and contract calls (e.g. precompiles), which would otherwise be rejected.

3. **USB Permissions on Linux**
3. **USB Permissions (Linux only)**

- If you're on Linux, you'll likely need a **udev rule** so your process can talk to the Ledger over USB/HID.
- Clone the official rules from → https://github.com/LedgerHQ/udev-rules
- Copy the provided `49-ledger.rules` into `/etc/udev/rules.d/`, then `sudo udevadm control --reload-rules` and replug your Ledger.
You'll need a **udev rule** so your process can talk to the Ledger over USB/HID. Clone the official rules from [LedgerHQ/udev-rules](https://github.com/LedgerHQ/udev-rules), copy `49-ledger.rules` into `/etc/udev/rules.d/`, then run `sudo udevadm control --reload-rules` and replug your Ledger.

4. **Install Dependencies**
```bash copy
npm install ethers @ethers-ext/signer-ledger @sei-js/evm @ledgerhq/hw-transport-node-hid
npm install ethers @ethers-ext/signer-ledger @ledgerhq/hw-transport-node-hid
```
- `@ethers-ext/signer-ledger` provides a `LedgerSigner` that wraps Ledger's USB/HID transport for Ethers.js.
- `@sei-js/evm` exports each precompile's address & ABI.

## Connecting Your Ledger to Sei via Ethers.js

**Why this matters:**

- The **provider** connects to the blockchain RPC.
- The **LedgerSigner** injects `signTransaction`/`signMessage` calls to your device.
- Every contract call or tx will require your physical confirmation on the Ledger.
## Connecting Your Ledger

```tsx copy
import { LedgerSigner } from '@ethers-ext/signer-ledger';
import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';
import { ethers } from 'ethers';

// 1. Create an RPC provider (here: Sei testnet)
const rpcUrl = 'https://evm-rpc-testnet.sei-apis.com';
const provider = new ethers.JsonRpcProvider(rpcUrl);

// 2. Initialize the LedgerSigner
// - TransportNodeHid handles the low-level USB/HID connection.
// - The signer will prompt your Ledger for each transaction.
const signer = new LedgerSigner(TransportNodeHid, provider);

// 3. (Optional) Confirm the address on-device
(async () => {
const addr = await signer.getAddress();
console.log('Using Ledger address:', addr);
})();
const addr = await signer.getAddress();
console.log('Using Ledger address:', addr);
```

## Governance Precompile Example
Every transaction sent through this signer will require physical confirmation on the Ledger device.

**Key points before you code:**
## Sending a Transfer

- **Precompiles** are optimized, built-in contracts—no external contract deployment needed.
- You must supply the **`value`** field in overrides to attach SEI.
- Every transaction pauses to let you **approve** on Ledger.
A simple example sending SEI from your Ledger to another address:

```tsx copy
import { GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI } from '@sei-js/evm';
import { LedgerSigner } from '@ethers-ext/signer-ledger';
import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';
import { ethers } from 'ethers';

/**
* Deposit SEI into a governance proposal.
*
* @param signer – an initialized LedgerSigner
* @param proposalId – the on-chain ID of the proposal you're participating in
* @param amount – how many SEI to lock (as a decimal string, e.g. "5")
*/
async function depositToProposal(signer: LedgerSigner, proposalId: number, amount: string) {
// 1. Instantiate the precompile contract
const gov = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, signer);

// 2. Prepare overrides to include SEI value
const overrides = {
value: ethers.parseEther(amount)
};

try {
// 3. Send the tx (this will prompt your Ledger to confirm)
const tx = await gov.deposit(proposalId, overrides);
console.log('Deposit TX sent:', tx.hash);
await tx.wait(); // wait for on-chain confirmation
console.log('✅ Deposit confirmed!');
} catch (err) {
console.error('❌ Deposit failed:', err);
}
}

/**
* Cast a vote on a governance proposal.
*
* @param signer – LedgerSigner
* @param proposalId – the proposal ID
* @param option – vote choice (1=Yes, 2=Abstain, 3=No, 4=NoWithVeto)
*/
async function castVote(signer: LedgerSigner, proposalId: number, option: number) {
const gov = new ethers.Contract(GOVERNANCE_PRECOMPILE_ADDRESS, GOVERNANCE_PRECOMPILE_ABI, signer);
try {
const tx = await gov.vote(proposalId, option);
console.log('Vote TX sent:', tx.hash);
await tx.wait();
console.log('✅ Vote recorded!');
} catch (err) {
console.error('❌ Vote failed:', err);
}
}

// Bring it all together
async function runGovernanceDemo() {
const proposalId = 1; // ← your target proposal
const depositAmount = '5'; // ← e.g. "5" SEI
const voteOption = 1; // ← Yes

// Deposit then vote
await depositToProposal(signer, proposalId, depositAmount);
await castVote(signer, proposalId, voteOption);
}

runGovernanceDemo();
```

## Staking via Precompile Example

**Before you run the code:**
const provider = new ethers.JsonRpcProvider('https://evm-rpc-testnet.sei-apis.com');
const signer = new LedgerSigner(TransportNodeHid, provider);

- The staking precompile is simply another in-chain contract that handles delegation logic.
- You must set both `value` (SEI to lock) **and** `from` (your EVM address).
- Gas limits on precompiles can be very low—start small and raise if you hit errors.
const tx = await signer.sendTransaction({
to: '0xRECIPIENT_ADDRESS',
value: ethers.parseEther('1.0')
});

```tsx copy
import { STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI } from '@sei-js/evm';

/**
* Stake SEI to a validator via the staking precompile.
*
* @param signer – LedgerSigner
* @param amount – decimal string of SEI to stake
* @param fromAddress – your EVM account address (for 'from' override)
* @param validatorAddress – the `seivaloper…` address of your validator
*/
async function stake(signer: LedgerSigner, amount: string, fromAddress: string, validatorAddress: string) {
const staking = new ethers.Contract(STAKING_PRECOMPILE_ADDRESS, STAKING_PRECOMPILE_ABI, signer);

// Attach SEI and explicitly set the 'from' so the precompile knows who's delegating
const overrides = {
from: fromAddress,
value: ethers.parseEther(amount),
// A minimal gas limit; adjust if you get underpriced errors
gasLimit: 100_000
};

console.log(`Staking ${amount} SEI → ${validatorAddress}`);
try {
const tx = await staking.delegate(validatorAddress, overrides);
console.log('Stake TX sent:', tx.hash);
await tx.wait();
console.log('✅ Stake confirmed!');
} catch (err) {
console.error('❌ Staking failed:', err);
}
}

// Demo runner
async function runStakingDemo() {
const validatorAddress = 'seivaloper…'; // ← your chosen validator
const defaultAddress = await signer.getAddress();

// Stake 5 SEI
await stake(signer, '5', defaultAddress, validatorAddress);
}

runStakingDemo();
console.log('TX sent:', tx.hash);
const receipt = await tx.wait();
console.log('Confirmed in block:', receipt.blockNumber);
```

## Additional Tips

- **Error Handling:**

- If the Ledger **times out**, increase the HID timeouts or ensure the device stays awake.
- If you see "blind signing required" errors, double-check the app settings on the device itself.
<Callout type="info">This signer works with any contract interaction — you can pass it to `ethers.Contract` constructors to sign [precompile](/evm/precompiles) calls, ERC-20 transfers, or any other EVM transaction.</Callout>

- **Reading Events & Logs:**
You can attach an `on("receipt", …)` or use `provider.getTransactionReceipt(tx.hash)` to inspect events emitted by
the precompile for richer UX.
## Troubleshooting

- **Security Reminder:**
Always verify the **contract address** and **ABI** match official Sei docs. Using a wrong address can lead to lost
funds.
- **Timeouts:** If the Ledger times out, increase the HID timeouts or ensure the device stays awake during signing.
- **"Blind signing required" errors:** Double-check that blind signing is enabled in the app settings on the device itself.
- **Connection failures:** Make sure no other application (e.g. Ledger Live) is holding the USB connection to your device.
5 changes: 5 additions & 0 deletions content/evm/sei-js/_meta.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
export default {
index: 'Introduction',
'create-sei': 'Scaffold Sei',
ledger: '@sei-js/ledger'
};
108 changes: 108 additions & 0 deletions content/evm/sei-js/create-sei.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
---
title: 'Scaffold Sei'
description: 'CLI tool for scaffolding production-ready Sei applications with pre-configured templates'
keywords: ['create-sei', 'scaffold', 'cli', 'sei', 'nextjs', 'wagmi', 'viem', 'template']
---

import { Callout, Steps, Tabs } from 'nextra/components';

# Scaffold Sei

`@sei-js/create-sei` is a CLI tool that scaffolds production-ready Sei dApps in seconds. Quickly spin up templates with Next.js, modern wallet integration, and TypeScript support.

```bash
npx @sei-js/create-sei app --name my-sei-app
```

Every generated project includes wallet connections, contract interactions, TypeScript, Tailwind CSS, Mantine UI, Biome for formatting, and responsive layouts — no additional setup required.

## Quick Start

You don't need to install `@sei-js/create-sei` globally. Use it directly with npx or pnpm:

<Tabs items={['npx', 'pnpm']}>
<Tabs.Tab>```bash npx @sei-js/create-sei app --name my-sei-app ```</Tabs.Tab>
<Tabs.Tab>```bash pnpm create @sei-js/create-sei app --name my-sei-app ```</Tabs.Tab>
</Tabs>

## Interactive Setup

<Steps>

### Run the CLI

Execute the create-sei command with your project name:

```bash
npx @sei-js/create-sei app
```

### Install and run

```bash
cd my-sei-app
npm install
npm run dev
```

### Start building

The CLI automatically configures TypeScript, Next.js, Tailwind CSS, Biome formatting, Mantine UI components, and Git initialization.

</Steps>

### CLI Options

| Command | Description |
| ----------------------- | ----------------------------------------------------- |
| `app` | Create a new Sei dApp |
| `app --name <name>` | Specify a project name (must be a valid package name) |
| `app --extension <ext>` | Add an optional extension to your project |
| `list-extensions` | List available extensions |

## Default Template

The default template creates a **Next.js + Wagmi (EVM)** application — a production-ready Next.js app with Wagmi for type-safe Ethereum wallet connections and blockchain interactions. Includes built-in support for MetaMask, WalletConnect, Coinbase Wallet, and other popular wallets.

**Tech Stack:** Next.js 14, Wagmi v2, Viem, TanStack Query, Tailwind CSS

```bash
npx @sei-js/create-sei app --name my-sei-app
```

## Extensions

Enhance your project with additional functionality using extensions.

### List Available Extensions

```bash
npx @sei-js/create-sei list-extensions
```

### Precompiles Extension

Add Sei precompile contract integration with examples for querying native blockchain data like token supply, staking info, and governance proposals.

```bash
npx @sei-js/create-sei app --name my-sei-precompile-app --extension precompiles
```

Includes Bank precompile, Staking precompile, and Governance precompile examples.

## What's Included

After running the CLI, you'll have a fully configured Sei dApp ready for development:

- **Project structure** — Organized file structure with components, hooks, and utilities
- **Wallet integration** — Pre-configured wallet connections and hooks
- **Development tools** — TypeScript, Biome, Mantine UI, and Tailwind CSS with sensible defaults
- **Sei network integration** — Built-in network configuration and contract interaction examples

<Callout type="info">**Prerequisites:** Node.js v18 or higher is required. Use `node --version` to verify your installation.</Callout>

## Troubleshooting

- **Node version conflicts** — Use `nvm use` to switch to the correct Node.js version
- **Permission errors** — Avoid using `sudo` with npm. Use `nvm` or fix npm permissions
- **Network timeouts** — Try switching to a different registry: `npm config set registry https://registry.npmjs.org/`
Loading
Loading