@asichain/asi-wallet-sdk 0.1.6 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,7 +12,7 @@
12
12
 
13
13
  Part of the [**Artificial Superintelligence Alliance**](https://superintelligence.io) ecosystem
14
14
 
15
- *Uniting Fetch.ai, SingularityNET, and CUDOS*
15
+ _Uniting Fetch.ai, SingularityNET, and CUDOS_
16
16
 
17
17
  </div>
18
18
 
@@ -35,18 +35,19 @@ Part of the [**Artificial Superintelligence Alliance**](https://superintelligenc
35
35
 
36
36
  ## Overview
37
37
 
38
- ASI Chain Wallet SDK is a lightweight, modular TypeScript library designed to simplify wallet integration and key management for [ASI Chain](https://github.com/asi-alliance/asi-chain) applications. It provides secure cryptographic operations, BIP-39/BIP-44 key derivation, encrypted storage mechanisms, and direct interaction with ASI Chain nodes.
38
+ ASI Chain Wallet SDK is a modular TypeScript library designed to simplify wallet integration and key management for [ASI Chain](https://github.com/asi-alliance/asi-chain) applications. It is organized around a high-level [`Client`](docs/DOMAINS.md) facade that manages multi-account HD wallets, secure encrypted storage, multi-network access, and reservation-aware transfers, while keeping secret material behind a strict signing boundary.
39
39
 
40
40
  ---
41
41
 
42
42
  ## Key Features
43
43
 
44
- - **Wallet Management** - Create, import, and derive wallets from private keys or mnemonic phrases via [WalletsService](docs/SERVICES.md)
45
- - **Secure Storage** - Password-based encryption using PBKDF2 + AES via [CryptoService](docs/SERVICES.md)
46
- - **Key Derivation** - BIP-39 mnemonic generation and BIP-44 hierarchical deterministic key derivation via [KeyDerivationService](docs/SERVICES.md)
47
- - **Vault System** - Encrypted container for managing multiple wallets and seeds via [Vault](docs/DOMAINS.md)
48
- - **Chain Interaction** - Transfer and balance operations via [AssetsService](docs/SERVICES.md) and [BlockchainGateway](docs/DOMAINS.md)
49
- - **Address Generation** - secp256k1 key generation with keccak256/blake2b address derivation via [KeysManager](docs/SERVICES.md)
44
+ - **Client Facade** - Single entry point for wallet lifecycle, networks, balances, and transfers via [Client](docs/DOMAINS.md)
45
+ - **Multi-Account HD Wallets** - Private-key and BIP-39/BIP-44 HD wallets with on-demand account derivation via [Wallet](docs/DOMAINS.md) and [Account](docs/DOMAINS.md)
46
+ - **Secure Key Handling** - PBKDF2 + AES-GCM encryption with key zeroization and a no-raw-export signing boundary via [CryptoService](docs/SERVICES.md) and [Signer](docs/DOMAINS.md)
47
+ - **Cross-Environment Storage** - IndexedDB (browser) and node-persist (Node.js) behind a shared table abstraction via [storage layer](docs/DOMAINS.md)
48
+ - **Pending-Transaction Reservations** - Persistent, reservation-aware available balance with deploy-status polling via [ReservationAdapter](docs/DOMAINS.md)
49
+ - **Multi-Network Access** - Runtime network switching over validator, read-only, and GraphQL indexer clients via [ApiClientManager](docs/DOMAINS.md)
50
+ - **Transaction History** - Indexed transfer history through a GraphQL anti-corruption layer via [AccountDataService](docs/SERVICES.md)
50
51
 
51
52
  ---
52
53
 
@@ -60,69 +61,82 @@ npm install @asichain/asi-wallet-sdk
60
61
 
61
62
  ## Quick Start
62
63
 
63
- ### Create a New Wallet
64
+ ### Create the Client
64
65
 
65
- ```typescript
66
- import { WalletsService, MnemonicService } from '@asichain/asi-wallet-sdk';
67
-
68
- // Generate a new wallet with random keys
69
- const wallet = WalletsService.createWallet();
70
- console.log('Address:', wallet.address);
71
- console.log('Public Key:', wallet.publicKey);
66
+ The [`Client`](docs/DOMAINS.md) is the single entry point. Provide a per-network
67
+ configuration and (optionally) a default network.
72
68
 
73
- // Create wallet from mnemonic
74
- const mnemonic = MnemonicService.generateMnemonic();
75
- const derivedWallet = await WalletsService.createWalletFromMnemonic(mnemonic, 0);
76
- console.log('Derived Address:', derivedWallet.address);
69
+ ```typescript
70
+ import { Client, type TNetworksConfig } from "@asichain/asi-wallet-sdk";
71
+
72
+ const networksConfig: TNetworksConfig = {
73
+ DevNet: {
74
+ ValidatorURL: "http://validator-node:40403",
75
+ ReadOnlyURL: "http://observer-node:40403",
76
+ IndexerURL: "http://indexer-node:8080",
77
+ },
78
+ Dev: { ValidatorURL: "", ReadOnlyURL: "", IndexerURL: "" },
79
+ MainNet: { ValidatorURL: "", ReadOnlyURL: "", IndexerURL: "" },
80
+ TestNet: { ValidatorURL: "", ReadOnlyURL: "", IndexerURL: "" },
81
+ };
82
+
83
+ const client = await Client.create({ networksConfig, defaultNetwork: "DevNet" });
77
84
  ```
78
85
 
79
- See [WalletsService](docs/SERVICES.md) and [MnemonicService](docs/SERVICES.md) for full API reference.
80
-
81
- ### Manage Wallets with Vault
86
+ ### Create Wallets
82
87
 
83
88
  ```typescript
84
- import { Vault, Wallet } from '@asichain/asi-wallet-sdk';
89
+ import { MnemonicStrength } from "@asichain/asi-wallet-sdk";
85
90
 
86
- // Create vault and add wallet
87
- const vault = new Vault();
91
+ // HD (mnemonic) wallet
92
+ const mnemonic = client.generateMnemonic(MnemonicStrength.TWELVE_WORDS);
93
+ const hdWallet = await client.createHDWallet(
94
+ { mnemonic, accountName: "Account 1" },
95
+ "wallet-password",
96
+ );
88
97
 
89
- // Add wallet to vault
90
- const wallet = await Wallet.fromPrivateKey('My Wallet', privateKey, 'wallet-password');
91
- vault.addWallet(wallet);
98
+ // Private-key wallet
99
+ const privateKey = client.generatePrivateKey();
100
+ const pkWallet = await client.createPrivateKeyWallet(
101
+ { privateKey, accountName: "Imported" },
102
+ "wallet-password",
103
+ );
92
104
 
93
- // Save vault to localStorage
94
- await vault.lock('vault-password');
95
- vault.save();
105
+ // Derive another account on the HD wallet
106
+ const { account } = await client.deriveAccount(
107
+ hdWallet.getId(),
108
+ "Account 2",
109
+ "wallet-password",
110
+ );
111
+ console.log("New address:", account.getAddress());
96
112
  ```
97
113
 
98
- See [Vault](docs/DOMAINS.md) and [Wallet](docs/DOMAINS.md) for full API reference.
114
+ See [Client](docs/DOMAINS.md), [Wallet](docs/DOMAINS.md), and [Account](docs/DOMAINS.md) for the full API reference.
99
115
 
100
116
  ### Check Balance and Transfer
101
117
 
102
118
  ```typescript
103
- import { AssetsService, BlockchainGateway } from '@asichain/asi-wallet-sdk';
104
-
105
- BlockchainGateway.init({
106
- validator: { baseUrl: 'http://validator-node:40403' },
107
- indexer: { baseUrl: 'http://observer-node:40403' },
108
- });
109
- const assetsService = new AssetsService();
110
-
111
- // Get ASI balance
112
- const balance = await assetsService.getASIBalance(address);
113
- console.log('Balance:', balance.toString());
114
-
115
- // Transfer tokens
116
- const deployId = await assetsService.transfer(
117
- fromAddress,
118
- toAddress,
119
- BigInt(1000000000), // 10 ASI in atomic units
120
- wallet,
121
- passwordProvider
119
+ const active = hdWallet.getActiveAccount()!;
120
+
121
+ // Total and reservation-aware available balance
122
+ const balance = await client.getBalance(active.getAddress());
123
+ const available = await client.getAvailableBalance(hdWallet.getId(), active.getId());
124
+ console.log("Balance:", client.toDisplayAmount(balance));
125
+
126
+ // Transfer tokens (amount in atomic units)
127
+ const deployId = await client.transfer(
128
+ {
129
+ walletId: hdWallet.getId(),
130
+ accountId: active.getId(),
131
+ to: recipientAddress,
132
+ amount: client.toAtomicAmount("10"), // 10 ASI
133
+ },
134
+ "wallet-password",
122
135
  );
136
+ console.log("Deploy id:", deployId);
123
137
  ```
124
138
 
125
- See [AssetsService](docs/SERVICES.md) for full API reference. For amount conversions, see [functions utilities](docs/UTILS.md).
139
+ See [Client](docs/DOMAINS.md) for the full API reference. For amount conversions, see [functions utilities](docs/UTILS.md).
126
140
 
127
141
  ---
128
142
 
@@ -140,34 +154,40 @@ See [AssetsService](docs/SERVICES.md) for full API reference. For amount convers
140
154
  │ ASI Wallet SDK │
141
155
  │ │
142
156
  │ ┌───────────────────────────────────────────────────────────────┐ │
143
- │ │ Services │ │
144
- │ │ • WalletsService - Wallet creation & address derivation│ │
145
- │ │ • CryptoService - Password-based encryption (AES) │ │
146
- │ │ • KeysManager - secp256k1 key generation │ │
147
- │ │ • KeyDerivationService - BIP-32/BIP-44 derivation │ │
148
- │ │ • MnemonicService - BIP-39 mnemonic handling │ │
149
- │ │ • SignerService - Deploy signing pipeline │ │
150
- │ │ • AssetsService - Balance + transfer operations │ │
151
- │ │ • FeeService - Gas fee calculations │ │
157
+ │ │ Client (facade) │ │
158
+ │ │ Wallet & account lifecycle networks balances transfers │ │
152
159
  │ └───────────────────────────────────────────────────────────────┘ │
153
160
  │ │
154
161
  │ ┌───────────────────────────────────────────────────────────────┐ │
155
162
  │ │ Domains │ │
156
- │ │ • Wallet - Encrypted wallet with lock/unlock │ │
157
- │ │ • Vault - Multi-wallet container │ │
163
+ │ │ • Wallet / Account - Multi-account HD & PK wallets │ │
164
+ │ │ • Signer (HD / PK) - No-raw-export signing boundary │ │
158
165
  │ │ • Asset - Token representation │ │
159
- │ │ • EncryptedRecord - Encrypted record storage │ │
160
- │ │ • BrowserStorage - Browser persistence adapter │ │
161
- │ │ • BlockchainGateway - Node API gateway │ │
166
+ │ │ • ReservationAdapter - Pending-transaction reservations │ │
167
+ │ │ • ApiClientManager - Per-network transport clients │ │
168
+ │ │ • ApiServiceRegistry - Service composition root │ │
169
+ │ │ • Storage repositories- Signers / Accounts / Reservations │ │
170
+ │ └───────────────────────────────────────────────────────────────┘ │
171
+ │ │
172
+ │ ┌───────────────────────────────────────────────────────────────┐ │
173
+ │ │ Services / Managers │ │
174
+ │ │ • WalletManager / AccountManager - In-memory ownership │ │
175
+ │ │ • StorageManager - Persistence orchestration │ │
176
+ │ │ • DeployService / BlockService / AccountDataService │ │
177
+ │ │ • AssetsService / TransactionService / DeployStatusPoller │ │
178
+ │ │ • CryptoService / KeysManager / KeyDerivation / Mnemonic │ │
179
+ │ └───────────────────────────────────────────────────────────────┘ │
180
+ │ │
181
+ │ ┌───────────────────────────────────────────────────────────────┐ │
182
+ │ │ Storage backends │ │
183
+ │ │ • BrowserStorage (IndexedDB) • NodeStorage (node-persist) │ │
184
+ │ │ selected automatically by environment │ │
162
185
  │ └───────────────────────────────────────────────────────────────┘ │
163
186
  │ │
164
187
  │ ┌───────────────────────────────────────────────────────────────┐ │
165
- │ │ Utils │ │
166
- │ │ • codec - Base16/Base58 encoding │ │
167
- │ │ • constants - Chain prefix, decimals, gas fees │ │
168
- │ │ • validators - Address and account name validation │ │
169
- │ │ • functions - Atomic amount conversions │ │
170
- │ │ • polyfills - Browser Buffer compatibility │ │
188
+ │ │ Utils / Config │ │
189
+ │ │ • codec / constants / validators / functions / polyfills │ │
190
+ │ │ • decorators / guards / fabrics │ │
171
191
  │ └───────────────────────────────────────────────────────────────┘ │
172
192
  └─────────────────────────────────────────────────────────────────────┘
173
193
 
@@ -176,9 +196,9 @@ See [AssetsService](docs/SERVICES.md) for full API reference. For amount convers
176
196
  │ ASI Chain Network │
177
197
  │ │
178
198
  │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
179
- │ │ Validator │ │ Validator │ │ Observer │ │
180
- │ │ Nodes │ │ Nodes │ │ Node │ │
181
- │ │ (Deploys) │ │ (Deploys) │ │ (Queries) │ │
199
+ │ │ Validator │ │ Observer │ │ Indexer │ │
200
+ │ │ Node │ │ Node │ │ (GraphQL) │ │
201
+ │ │ (Deploys) │ │ (Queries) │ │ (History) │ │
182
202
  │ └──────────────┘ └──────────────┘ └──────────────┘ │
183
203
  └─────────────────────────────────────────────────────────────────────┘
184
204
  ```
@@ -198,23 +218,25 @@ See [AssetsService](docs/SERVICES.md) for full API reference. For amount convers
198
218
  ```
199
219
  asi-chain-wallet-sdk/
200
220
  ├── src/ # SDK source code
201
- │ ├── config/ # Configuration and constants
202
- │ ├── domains/ # Domain models (→ docs/DOMAINS.md)
203
- │ ├── services/ # Business logic (→ docs/SERVICES.md)
204
- │ ├── utils/ # Utilities (→ docs/UTILS.md)
221
+ │ ├── config/ # Runtime defaults and constants
222
+ │ ├── domains/ # Domain models & transport (→ docs/DOMAINS.md)
223
+ │ ├── services/ # Managers & business logic (→ docs/SERVICES.md)
224
+ │ ├── fabrics/ # Environment-aware factories (storage)
225
+ │ ├── utils/ # Utilities & guards (→ docs/UTILS.md)
205
226
  │ └── index.ts # Main export
206
227
 
207
228
  ├── playground/ # React demo app (→ docs/PLAYGROUND.md)
208
229
  │ ├── src/
230
+ │ │ ├── sdk-react-kit/ # SDK ↔ React integration layer (hooks, context)
209
231
  │ │ ├── components/ # UI components
210
- │ │ ├── pages/ # WalletsPage demo
211
- │ │ └── config/ # Network configuration
232
+ │ │ ├── pages/ # WalletsPage, TxHistoryPage
233
+ │ │ └── router/ # Client-side routing
212
234
  │ └── package.json
213
235
 
214
236
  ├── docs/ # API reference
215
- │ ├── DOMAINS.md # Domain models
216
- │ ├── SERVICES.md # Services
217
- │ ├── UTILS.md # Utilities
237
+ │ ├── DOMAINS.md # Domain models & transport
238
+ │ ├── SERVICES.md # Managers & services
239
+ │ ├── UTILS.md # Utilities & config
218
240
  │ └── PLAYGROUND.md # Playground components
219
241
 
220
242
  ├── package.json # SDK dependencies
@@ -228,33 +250,33 @@ asi-chain-wallet-sdk/
228
250
 
229
251
  ### SDK Reference
230
252
 
231
- | Document | Description |
232
- |----------|-------------|
233
- | [docs/DOMAINS.md](docs/DOMAINS.md) | Domain models (`Wallet`, `Vault`, `Asset`, `BlockchainGateway`, and related types) |
234
- | [docs/SERVICES.md](docs/SERVICES.md) | Service layer (`WalletsService`, `CryptoService`, `KeysManager`, `KeyDerivationService`, `SignerService`, `AssetsService`, `DeployResubmitter`) |
235
- | [docs/UTILS.md](docs/UTILS.md) | Utility helpers (`codec`, `constants`, `validators`, `functions`, `polyfills`) |
236
- | [docs/PLAYGROUND.md](docs/PLAYGROUND.md) | Playground components and usage examples |
253
+ | Document | Description |
254
+ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
255
+ | [docs/DOMAINS.md](docs/DOMAINS.md) | Domain models & transport (`Client`, `Wallet`, `Account`, `Signer`, `ReservationAdapter`, `ApiClientManager`, storage repositories, and types) |
256
+ | [docs/SERVICES.md](docs/SERVICES.md) | Managers & services (`WalletManager`, `AccountManager`, `StorageManager`, `DeployService`, `AssetsService`, `TransactionService`, `CryptoService`) |
257
+ | [docs/UTILS.md](docs/UTILS.md) | Utilities & config (`codec`, `constants`, `validators`, `functions`, `guards`, `decorators`, `fabrics`, `polyfills`) |
258
+ | [docs/PLAYGROUND.md](docs/PLAYGROUND.md) | Playground components, the `sdk-react-kit` integration layer, and usage examples |
237
259
 
238
260
  ### Related Resources
239
261
 
240
- | Resource | Link |
241
- |----------|------|
242
- | ASI Chain Documentation | https://docs.asichain.io |
243
- | ASI Chain Node | [github.com/asi-alliance/asi-chain](https://github.com/asi-alliance/asi-chain) |
244
- | ASI Chain Wallet | [github.com/asi-alliance/asi-chain-wallet](https://github.com/asi-alliance/asi-chain-wallet) |
245
- | ASI Chain Explorer | [github.com/asi-alliance/asi-chain-explorer](https://github.com/asi-alliance/asi-chain-explorer) |
246
- | ASI Chain Faucet | [github.com/asi-alliance/asi-chain-faucet](https://github.com/asi-alliance/asi-chain-faucet) |
262
+ | Resource | Link |
263
+ | ----------------------- | ------------------------------------------------------------------------------------------------ |
264
+ | ASI Chain Documentation | https://docs.asichain.io |
265
+ | ASI Chain Node | [github.com/asi-alliance/asi-chain](https://github.com/asi-alliance/asi-chain) |
266
+ | ASI Chain Wallet | [github.com/asi-alliance/asi-chain-wallet](https://github.com/asi-alliance/asi-chain-wallet) |
267
+ | ASI Chain Explorer | [github.com/asi-alliance/asi-chain-explorer](https://github.com/asi-alliance/asi-chain-explorer) |
268
+ | ASI Chain Faucet | [github.com/asi-alliance/asi-chain-faucet](https://github.com/asi-alliance/asi-chain-faucet) |
247
269
 
248
270
  ---
249
271
 
250
272
  ## Security
251
273
 
252
- | Document | Description |
253
- |----------|-------------|
254
- | [SECURITY.md](SECURITY.md) | Vulnerability reporting policy, disclosure process, and supported versions |
255
- | [THREAT_MODEL.md](THREAT_MODEL.md) | Threat assumptions, trust boundaries, adversary model, and mitigations |
256
- | [SECURITY_INVARIANTS.md](SECURITY_INVARIANTS.md) | Non-negotiable key/storage/signing/documentation security guarantees |
257
- | [CRYPTO_PROFILE.md](CRYPTO_PROFILE.md) | Versioned crypto parameters, key-handling profile, and migration notes |
274
+ | Document | Description |
275
+ | ------------------------------------------------ | -------------------------------------------------------------------------- |
276
+ | [SECURITY.md](SECURITY.md) | Vulnerability reporting policy, disclosure process, and supported versions |
277
+ | [THREAT_MODEL.md](THREAT_MODEL.md) | Threat assumptions, trust boundaries, adversary model, and mitigations |
278
+ | [SECURITY_INVARIANTS.md](SECURITY_INVARIANTS.md) | Non-negotiable key/storage/signing/documentation security guarantees |
279
+ | [CRYPTO_PROFILE.md](CRYPTO_PROFILE.md) | Versioned crypto parameters, key-handling profile, and migration notes |
258
280
 
259
281
  ---
260
282
 
@@ -289,35 +311,40 @@ The [playground](playground) provides a React-based demo application for testing
289
311
  cd playground
290
312
  npm install
291
313
 
292
- # Create .env file with network configuration
293
- # VITE_NETWORKS='[{"name":"DevNet","validatorURL":"...","readOnlyURL":"..."}]'
314
+ # Create .env file with per-network endpoints, e.g.:
315
+ # VITE_DEFAULT_NETWORK=DevNet
316
+ # VITE_DEVNET_VALIDATOR_URL=...
317
+ # VITE_DEVNET_READONLY_URL=...
318
+ # VITE_DEVNET_INDEXER_URL=...
294
319
 
295
320
  npm run dev
296
321
  ```
297
322
 
298
- Playground available at `http://localhost:5173`. See [docs/PLAYGROUND.md](docs/PLAYGROUND.md) for component details.
323
+ Playground available at `http://localhost:3000`. See [docs/PLAYGROUND.md](docs/PLAYGROUND.md) for component details.
299
324
 
300
325
  ### Dependencies
301
326
 
302
327
  **SDK** ([package.json](package.json)):
303
328
 
304
- | Package | Version | Purpose |
305
- |---------|---------|---------|
306
- | [axios](https://github.com/axios/axios) | 1.13.2 | HTTP client for node communication |
307
- | [bip32](https://github.com/bitcoinjs/bip32) | 4.0.0 | BIP-32 hierarchical deterministic wallets |
308
- | [bip39](https://github.com/bitcoinjs/bip39) | 3.1.0 | BIP-39 mnemonic generation |
309
- | [blakejs](https://github.com/dcposch/blakejs) | 1.2.1 | BLAKE2b hashing for addresses |
310
- | [bs58](https://github.com/cryptocoinjs/bs58) | 6.0.0 | Base58 encoding |
311
- | [@noble/hashes](https://github.com/paulmillr/noble-hashes) | 1.6.0 | Cryptographic hash helpers |
312
- | [@noble/secp256k1](https://github.com/paulmillr/noble-secp256k1) | 1.7.0 | secp256k1 key generation and signing |
313
- | [js-sha3](https://github.com/nicknisi/js-sha3) | 0.9.3 | keccak256 hashing |
329
+ | Package | Version | Purpose |
330
+ | ---------------------------------------------------------------- | ------- | ----------------------------------------- |
331
+ | [axios](https://github.com/axios/axios) | 1.13.2 | HTTP client for node communication |
332
+ | [bip32](https://github.com/bitcoinjs/bip32) | 4.0.0 | BIP-32 hierarchical deterministic wallets |
333
+ | [bip39](https://github.com/bitcoinjs/bip39) | 3.1.0 | BIP-39 mnemonic generation |
334
+ | [blakejs](https://github.com/dcposch/blakejs) | 1.2.1 | BLAKE2b hashing for addresses |
335
+ | [bs58](https://github.com/cryptocoinjs/bs58) | 6.0.0 | Base58 encoding |
336
+ | [@noble/hashes](https://github.com/paulmillr/noble-hashes) | 1.6.0 | Cryptographic hash helpers |
337
+ | [@noble/secp256k1](https://github.com/paulmillr/noble-secp256k1) | 1.7.0 | secp256k1 key generation and signing |
338
+ | [js-sha3](https://github.com/nicknisi/js-sha3) | 0.9.3 | keccak256 hashing |
339
+ | [node-persist](https://github.com/simonlast/node-persist) | 4.0.4 | Node.js storage backend |
340
+ | [buffer](https://github.com/feross/buffer) | 6.0.3 | Browser Buffer compatibility |
314
341
 
315
342
  **Playground** ([playground/package.json](playground/package.json)):
316
343
 
317
- | Package | Version | Purpose |
318
- |---------|---------|---------|
319
- | [react](https://react.dev) | 18.2.0 | UI framework |
320
- | [vite](https://vite.dev) | 7.2.6 | Build tool and dev server |
344
+ | Package | Version | Purpose |
345
+ | -------------------------- | ------- | ------------------------- |
346
+ | [react](https://react.dev) | 18.2.0 | UI framework |
347
+ | [vite](https://vite.dev) | 7.2.6 | Build tool and dev server |
321
348
 
322
349
  ---
323
350