Skip to content

Commit 4580596

Browse files
alia-bitgoalia-bitgo
authored
feat: update scripts for go account creation
2 parents 420d9a6 + bd893c9 commit 4580596

4 files changed

Lines changed: 666 additions & 22 deletions

File tree

‎examples/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44

55
In this directory, you can find examples on how to use the BitGoJS SDK with TypeScript. These examples use modern TypeScript/ES6 syntax with `async`/`await`. This is the recommended way to use the BitGoJS SDK for new projects.
66

7+
### Go Accounts (Trading Wallets)
8+
9+
Go Accounts are trading wallets that don't require BitGo Express. See the [detailed guide](./docs/go-account-creation.md) for more information.
10+
11+
- [Create Go Account (SDK Approach - Recommended)](./ts/create-go-account.ts) - Simple, high-level wallet creation
12+
- [Create Go Account (Advanced SDK Approach)](./ts/create-go-account-advanced.ts) - Manual keychain control for advanced users
13+
714
### Wallet
815

916
- [Backup Key Creation](./ts/backup-key-creation.ts)

‎examples/docs/go-account-creation.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Creating Go Accounts without BitGo Express
2+
3+
This guide demonstrates how to create Go Accounts (trading wallets) using only the BitGo SDK, without requiring BitGo Express.
4+
5+
## Overview
6+
7+
**BitGo Express is optional middleware** - you can interact directly with the BitGo platform using the SDK. This approach gives you:
8+
- Direct API communication with BitGo
9+
- No need to run a separate Express server
10+
- Full control over the wallet creation process
11+
- Production-ready code with proper error handling
12+
13+
## Two Approaches
14+
15+
### 1. SDK Approach (Recommended)
16+
**File:** `examples/ts/create-go-account.ts`
17+
18+
Uses the high-level `generateWallet()` method which handles keychain creation, encryption, and wallet setup automatically.
19+
20+
**Best for:**
21+
- Most production use cases
22+
- Quick integration
23+
- Users who don't need manual key management
24+
25+
**Example:**
26+
```typescript
27+
const bitgo = new BitGoAPI({
28+
accessToken: process.env.TESTNET_ACCESS_TOKEN,
29+
env: 'test',
30+
});
31+
32+
const coin = 'ofc';
33+
bitgo.register(coin, coins.Ofc.createInstance);
34+
35+
const response = await bitgo.coin(coin).wallets().generateWallet({
36+
label: 'My Go Account',
37+
passphrase: 'wallet_passphrase',
38+
passcodeEncryptionCode: 'encryption_code',
39+
enterprise: 'your_enterprise_id',
40+
type: 'trading', // Required for Go Accounts
41+
});
42+
43+
const { wallet, userKeychain, encryptedWalletPassphrase } = response;
44+
```
45+
46+
### 2. Advanced SDK Approach
47+
**File:** `examples/ts/create-go-account-advanced.ts`
48+
49+
Provides manual control over keychain creation and wallet setup using SDK methods.
50+
51+
**Best for:**
52+
- Advanced users needing custom key management
53+
- Integration with custom key storage systems
54+
- Understanding the internals of Go Account creation
55+
- Testing and debugging
56+
57+
**Example:**
58+
```typescript
59+
// Step 1: Create keychain locally
60+
const keychain = bitgo.coin('ofc').keychains().create();
61+
62+
// Step 2: Encrypt private key
63+
const encryptedPrv = bitgo.encrypt({
64+
password: passphrase,
65+
input: keychain.prv
66+
});
67+
68+
// Step 3: Add keychain to BitGo
69+
const addedKeychain = await bitgo.coin('ofc').keychains().add({
70+
pub: keychain.pub,
71+
encryptedPrv: encryptedPrv,
72+
originalPasscodeEncryptionCode: passcodeEncryptionCode,
73+
keyType: 'independent',
74+
source: 'user',
75+
enterprise: enterpriseId,
76+
});
77+
78+
// Step 4: Create wallet
79+
const walletResponse = await bitgo.coin('ofc').wallets().add({
80+
label: 'My Go Account',
81+
m: 1,
82+
n: 1,
83+
keys: [addedKeychain.id],
84+
type: 'trading',
85+
enterprise: enterpriseId,
86+
});
87+
```
88+
89+
## Complete Workflow
90+
91+
Both examples demonstrate the complete Go Account creation flow:
92+
93+
### 1. Create Wallet
94+
```typescript
95+
// SDK generates keychain and wallet in one call
96+
const response = await bitgo.coin('ofc').wallets().generateWallet({...});
97+
```
98+
99+
### 2. Wait for Initialization
100+
Go Accounts require system initialization, which may take a few seconds:
101+
102+
```typescript
103+
async function waitForWalletInitialization(wallet, maxRetries = 30, delayMs = 2000) {
104+
for (let attempt = 1; attempt <= maxRetries; attempt++) {
105+
const walletData = await bitgo.coin('ofc').wallets().get({ id: wallet.id() });
106+
const coinSpecific = walletData._wallet.coinSpecific;
107+
108+
if (!coinSpecific.pendingSystemInitialization) {
109+
return; // Wallet ready
110+
}
111+
112+
await sleep(delayMs);
113+
}
114+
}
115+
```
116+
117+
### 3. Create Addresses
118+
**IMPORTANT:** For Go Account (OFC) wallets, the `onToken` parameter is **always required** when creating addresses. There is no "default" address - every address must be associated with a specific token.
119+
120+
```typescript
121+
// Create a token-specific address (onToken is mandatory)
122+
const tokenAddress = await wallet.createAddress({
123+
label: 'USDC Address',
124+
onToken: 'ofctsol:usdc' // Required for OFC wallets
125+
});
126+
127+
// Create addresses for different tokens
128+
const usdtAddress = await wallet.createAddress({
129+
label: 'USDT Address',
130+
onToken: 'ofcttrx:usdt'
131+
});
132+
```
133+
134+
## Key Differences from Express Approach
135+
136+
| Aspect | Express | Direct SDK |
137+
|--------|---------|------------|
138+
| **Server Required** | Yes (Express server) | No |
139+
| **API Calls** | HTTP to Express → Express to BitGo | Direct SDK → BitGo |
140+
| **Setup** | More complex (server + SDK) | Simple (SDK only) |
141+
| **Security** | Keys never leave Express server | Keys managed in your application |
142+
| **Performance** | Extra network hop | Direct communication |
143+
| **Use Case** | Shared signing server | Embedded integration |
144+
145+
## Security Best Practices
146+
147+
1. **Backup Critical Information:**
148+
- Encrypted private key (`userKeychain.encryptedPrv`)
149+
- Keychain ID (`userKeychain.id`)
150+
- Encrypted wallet passphrase (`encryptedWalletPassphrase`)
151+
- Passphrase encryption code (stored separately)
152+
153+
2. **Secure Storage:**
154+
- Store encrypted keys in secure database
155+
- Never log unencrypted private keys
156+
- Use environment variables for sensitive config
157+
158+
3. **Access Control:**
159+
- Limit access token permissions
160+
- Use enterprise-scoped tokens
161+
- Implement proper authentication
162+
163+
## Running the Examples
164+
165+
1. Install dependencies:
166+
```bash
167+
cd /path/to/BitGoJS
168+
yarn install
169+
```
170+
171+
2. Set up environment:
172+
```bash
173+
cp examples/.env.example examples/.env
174+
# Edit .env with your access token and enterprise ID
175+
```
176+
177+
3. Update script configuration:
178+
- Set your `enterprise` ID
179+
- Choose wallet `label` and `passphrase`
180+
- Optional: Set `token` for specific crypto assets
181+
182+
4. Run the script:
183+
```bash
184+
cd examples/ts
185+
npx tsx create-go-account.ts
186+
# or for advanced approach:
187+
npx tsx create-go-account-advanced.ts
188+
```
189+
190+
## Supported Tokens
191+
192+
Common tokens for Go Accounts (use with `onToken` parameter):
193+
194+
### Testnet Tokens
195+
Stablecoins:
196+
- `ofctsol:usdc` - USD Coin on Solana testnet
197+
- `ofctsol:usdt` - USD Tether on Solana testnet
198+
- `ofcttrx:usdt` - USDT on Tron testnet
199+
200+
Native/Wrapped Tokens:
201+
- `ofcbtc` - Bitcoin
202+
- `ofceth` - Ethereum
203+
- `ofctsol:wsol` - Wrapped SOL on Solana testnet
204+
- `ofctsol:ray` - Raydium on Solana testnet
205+
- `ofctsol:srm` - Serum on Solana testnet
206+
207+
### Mainnet Tokens (use when `env: 'production'`)
208+
Stablecoins:
209+
- `ofcsol:usdc` - USD Coin on Solana
210+
- `ofcsol:usdt` - USD Tether on Solana
211+
- `ofcpolygon:usdc` - USD Coin on Polygon
212+
- `ofcarbeth:usdc` - USD Coin on Arbitrum
213+
- `ofcbsc:usdc` - USD Coin on BSC
214+
215+
Native/Wrapped Tokens:
216+
- `ofcbtc` - Bitcoin
217+
- `ofceth` - Ethereum
218+
- `ofcsol:wsol` - Wrapped SOL on Solana
219+
- `ofcpolygon:matic` - MATIC on Polygon
220+
221+
**Note:** Token names use the format `ofc[network]:[token]` (e.g., `ofcsol:usdc`) for chain-specific tokens, or just `ofc[coin]` (e.g., `ofcbtc`) for native coins.
222+
223+
## Troubleshooting
224+
225+
### Wallet initialization timeout
226+
**Issue:** Wallet stuck in `pendingSystemInitialization`
227+
228+
**Solution:** Increase the retry count and delay in `waitForWalletInitialization()`.
229+
230+
### Token address creation fails
231+
**Issue:** Error "onToken is a mandatory parameter for OFC wallets"
232+
233+
**Solution:** Always include the `onToken` parameter when creating addresses for Go Account wallets. There is no default address - every address must specify a token.
234+
235+
**Issue:** Error "Coin unsupported: [token]"
236+
237+
**Solution:**
238+
- Verify the token name format is correct (e.g., `ofctsol:usdc` for testnet, `ofcsol:usdc` for mainnet)
239+
- Check that the token is enabled for your enterprise
240+
- Ensure you're using testnet tokens (`ofct...`) with `env: 'test'` and mainnet tokens (`ofc...`) with `env: 'production'`
241+
242+
## Additional Resources
243+
244+
- [BitGo API Documentation](https://developers.bitgo.com/)
245+
- [Go Accounts Overview](https://developers.bitgo.com/docs/crypto-as-a-service-go-accounts)
246+
- [SDK Reference](https://github.com/BitGo/BitGoJS)
247+
248+
## Support
249+
250+
For questions or issues:
251+
1. Check the [BitGo Developer Documentation](https://developers.bitgo.com/)
252+
2. Open an issue on [GitHub](https://github.com/BitGo/BitGoJS/issues)
253+
3. Contact BitGo support

0 commit comments

Comments
 (0)