Skip to content

Commit b1154a7

Browse files
devin-ai-integration[bot]pyramation
devin-ai-integration[bot]
and
pyramation
committed
Add Bitcoin network implementation with signing, accounts, and testing
Co-Authored-By: Dan Lynch <[email protected]>
1 parent fe6044e commit b1154a7

File tree

20 files changed

+1727
-0
lines changed

20 files changed

+1727
-0
lines changed

‎.github/workflows/bitcoin-e2e-tests.yaml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Bitcoin E2E Tests
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
jobs:
13+
networks-bitcoin:
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Checkout Repository 📝
18+
uses: actions/checkout@v4
19+
20+
- name: Setup Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: "20.x"
24+
cache: "yarn"
25+
26+
- name: Install Dependencies
27+
run: yarn install --frozen-lockfile
28+
29+
- name: Build Project
30+
run: yarn build
31+
32+
- name: Run Tests
33+
run: cd ./networks/bitcoin && yarn jest

‎.github/workflows/e2e-tests.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,3 +93,25 @@ jobs:
9393

9494
- name: Run E2E Tests
9595
run: cd ./networks/ethereum && yarn starship:test && yarn test:utils
96+
97+
networks-bitcoin:
98+
runs-on: ubuntu-latest
99+
100+
steps:
101+
- name: Checkout Repository 📝
102+
uses: actions/checkout@v4
103+
104+
- name: Setup Node.js
105+
uses: actions/setup-node@v4
106+
with:
107+
node-version: "20.x"
108+
cache: "yarn"
109+
110+
- name: Install Dependencies
111+
run: yarn install --frozen-lockfile
112+
113+
- name: Build Project
114+
run: yarn build
115+
116+
- name: Run Tests
117+
run: cd ./networks/bitcoin && yarn jest

‎docs/adding-a-new-network.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Adding a New Network to InterchainJS
2+
3+
This guide explains how to add a new blockchain network to the InterchainJS project.
4+
5+
## Overview
6+
7+
InterchainJS is designed to be a universal signing interface for various blockchain networks. Adding a new network involves implementing the necessary components to interact with that blockchain, including:
8+
9+
1. Transaction signing
10+
2. Account management
11+
3. RPC communication
12+
4. Testing infrastructure
13+
14+
## Directory Structure
15+
16+
When adding a new network, follow this directory structure:
17+
18+
```
19+
networks/
20+
└── your-network/
21+
├── package.json
22+
├── tsconfig.json
23+
├── tsconfig.esm.json
24+
├── README.md
25+
├── src/
26+
│ ├── index.ts
27+
│ ├── signers/
28+
│ │ └── [Signer implementations]
29+
│ ├── utils/
30+
│ │ └── [Utility functions]
31+
│ ├── types/
32+
│ │ └── [Type definitions]
33+
│ └── rpc/
34+
│ └── [RPC client implementation]
35+
└── starship/
36+
├── configs/
37+
│ └── [Starship configuration files]
38+
└── __tests__/
39+
└── [Test files]
40+
```
41+
42+
## Implementation Steps
43+
44+
### 1. Create the Basic Structure
45+
46+
Start by creating the directory structure and basic configuration files:
47+
48+
```bash
49+
mkdir -p networks/your-network/src/{signers,utils,types,rpc}
50+
mkdir -p networks/your-network/starship/{configs,__tests__}
51+
```
52+
53+
### 2. Configure package.json
54+
55+
Create a `package.json` file with the necessary dependencies and scripts:
56+
57+
```json
58+
{
59+
"name": "@interchainjs/your-network",
60+
"version": "1.11.11",
61+
"description": "Transaction codec and client to communicate with your-network blockchain",
62+
"main": "index.js",
63+
"module": "esm/index.js",
64+
"types": "index.d.ts",
65+
"author": "Hyperweb <[email protected]>",
66+
"homepage": "https://github.com/hyperweb-io/interchainjs",
67+
"repository": {
68+
"type": "git",
69+
"url": "https://github.com/hyperweb-io/interchainjs"
70+
},
71+
"license": "MIT",
72+
"publishConfig": {
73+
"access": "public",
74+
"directory": "dist"
75+
},
76+
"scripts": {
77+
"copy": "copyfiles -f ../../LICENSE-MIT ../../LICENSE-Apache README.md package.json dist",
78+
"clean": "rimraf dist/**",
79+
"prepare": "npm run build",
80+
"build": "npm run clean; tsc; tsc -p tsconfig.esm.json; npm run copy",
81+
"build:dev": "npm run clean; tsc --declarationMap; tsc -p tsconfig.esm.json; npm run copy",
82+
"lint": "eslint . --fix",
83+
"starship": "starship --config ./starship/configs/your-network.yaml",
84+
"starship:stop": "starship stop",
85+
"starship:test": "npx jest --preset ts-jest starship/__tests__/token.test.ts"
86+
},
87+
"dependencies": {
88+
"@interchainjs/types": "1.11.11",
89+
"@interchainjs/utils": "1.11.11",
90+
// Add network-specific dependencies here
91+
},
92+
"keywords": [
93+
"your-network",
94+
"blockchain",
95+
"transaction"
96+
]
97+
}
98+
```
99+
100+
### 3. Define Types
101+
102+
Create type definitions for your network in the `src/types/` directory:
103+
104+
- `signer.ts`: Define interfaces for signers
105+
- `transaction.ts`: Define transaction-related types
106+
- `network.ts`: Define network configuration
107+
- `index.ts`: Export all types
108+
109+
### 4. Implement Signers
110+
111+
Create signer implementations in the `src/signers/` directory. Typically, you'll want to implement:
112+
113+
- A signer that works with private keys
114+
- A signer that works with browser wallets (if applicable)
115+
116+
### 5. Implement RPC Client
117+
118+
Create an RPC client in the `src/rpc/` directory to communicate with the blockchain:
119+
120+
- Define methods for interacting with the blockchain
121+
- Handle authentication and error handling
122+
- Implement transaction broadcasting
123+
124+
### 6. Implement Utilities
125+
126+
Create utility functions in the `src/utils/` directory:
127+
128+
- Address validation and formatting
129+
- Denomination conversions
130+
- Common helper functions
131+
132+
### 7. Create Main Exports
133+
134+
Create an `index.ts` file to export all the components:
135+
136+
```typescript
137+
// Main exports
138+
export * from './signers/YourSigner';
139+
140+
// Types
141+
export * from './types';
142+
143+
// Utils
144+
export * from './utils/address';
145+
export * from './utils/common';
146+
147+
// RPC
148+
export * from './rpc/client';
149+
```
150+
151+
### 8. Configure Starship for Testing
152+
153+
Create a Starship configuration file in `starship/configs/` to set up a test environment for your network.
154+
155+
### 9. Write Tests
156+
157+
Create test files in `starship/__tests__/` to test your implementation.
158+
159+
### 10. Create Documentation
160+
161+
Write a comprehensive README.md file explaining how to use your network implementation.
162+
163+
### 11. Update GitHub Workflows
164+
165+
Add your network to the GitHub workflows for testing.
166+
167+
## Starship Integration
168+
169+
To add support for a new chain in Starship, follow these steps:
170+
171+
1. Build a Docker image for the chain – ensure it includes the chain binary and standard utilities.
172+
2. Add chain defaults in the Helm chart – insert a new entry under defaultChains in starship/charts/defaults.yaml.
173+
3. Update the schema – include the chain name in the enum at .properties.chains.items.properties.name.enum within starship/charts/devnet/values.schema.json.
174+
4. Create an end‑to‑end test configuration in starship/tests/e2e/configs.
175+
5. Open a PR with the Docker image configuration, Helm changes, and tests once everything works.
176+
177+
## Phased Implementation Approach
178+
179+
When implementing a new network, consider using a phased approach:
180+
181+
### Phase 1: Essential Core
182+
183+
- RPC client for basic blockchain interaction
184+
- Transaction signing and broadcasting
185+
- Address generation and validation
186+
- Basic wallet functionality
187+
- Network configuration (mainnet, testnet, etc.)
188+
189+
### Phase 2: Advanced Transactions
190+
191+
- Support for complex transaction types
192+
- Multi-signature support
193+
- Advanced scripting capabilities
194+
- Enhanced security features
195+
196+
### Phase 3: Wallet Integrations & Light Clients
197+
198+
- Hardware wallet support
199+
- Browser wallet integrations
200+
- Light client implementations
201+
- Advanced features specific to the network
202+
203+
## Best Practices
204+
205+
1. **Follow Existing Patterns**: Look at existing network implementations (Cosmos, Ethereum, Injective, Bitcoin) for guidance.
206+
2. **Type Safety**: Ensure all functions and interfaces are properly typed.
207+
3. **Error Handling**: Implement proper error handling for RPC calls and other operations.
208+
4. **Documentation**: Document all public APIs and provide usage examples.
209+
5. **Testing**: Write comprehensive tests for all functionality.
210+
6. **Modular Design**: Design your implementation to be modular and extensible.
211+
7. **Minimal Dependencies**: Use minimal dependencies to keep the package lightweight.

0 commit comments

Comments
 (0)