@amadeus-protocol/sdk 1.0.8 → 1.1.1

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.
Files changed (200) hide show
  1. package/README.md +215 -30
  2. package/dist/api/chain.d.ts +144 -117
  3. package/dist/api/chain.d.ts.map +1 -1
  4. package/dist/api/chain.js +175 -146
  5. package/dist/api/chain.js.map +1 -1
  6. package/dist/api/contract.d.ts +78 -60
  7. package/dist/api/contract.d.ts.map +1 -1
  8. package/dist/api/contract.js +102 -75
  9. package/dist/api/contract.js.map +1 -1
  10. package/dist/api/epoch.d.ts +65 -66
  11. package/dist/api/epoch.d.ts.map +1 -1
  12. package/dist/api/epoch.js +90 -98
  13. package/dist/api/epoch.js.map +1 -1
  14. package/dist/api/peer.d.ts +77 -78
  15. package/dist/api/peer.d.ts.map +1 -1
  16. package/dist/api/peer.js +93 -94
  17. package/dist/api/peer.js.map +1 -1
  18. package/dist/api/proof.d.ts +44 -23
  19. package/dist/api/proof.d.ts.map +1 -1
  20. package/dist/api/proof.js +56 -29
  21. package/dist/api/proof.js.map +1 -1
  22. package/dist/api/transaction.d.ts +68 -69
  23. package/dist/api/transaction.d.ts.map +1 -1
  24. package/dist/api/transaction.js +84 -84
  25. package/dist/api/transaction.js.map +1 -1
  26. package/dist/api/wallet.d.ts +36 -37
  27. package/dist/api/wallet.d.ts.map +1 -1
  28. package/dist/api/wallet.js +47 -50
  29. package/dist/api/wallet.js.map +1 -1
  30. package/dist/client.d.ts +66 -68
  31. package/dist/client.d.ts.map +1 -1
  32. package/dist/client.js +231 -276
  33. package/dist/client.js.map +1 -1
  34. package/dist/constants.d.ts +13 -10
  35. package/dist/constants.d.ts.map +1 -1
  36. package/dist/constants.js +49 -45
  37. package/dist/constants.js.map +1 -1
  38. package/dist/contract-state.d.ts +6 -3
  39. package/dist/contract-state.d.ts.map +1 -1
  40. package/dist/contract-state.js +88 -106
  41. package/dist/contract-state.js.map +1 -1
  42. package/dist/contracts/abi-types.d.ts +32 -32
  43. package/dist/contracts/abi-types.d.ts.map +1 -1
  44. package/dist/contracts/coin.d.ts +13 -20
  45. package/dist/contracts/coin.d.ts.map +1 -1
  46. package/dist/contracts/coin.js +42 -38
  47. package/dist/contracts/coin.js.map +1 -1
  48. package/dist/contracts/contract-call.d.ts +14 -16
  49. package/dist/contracts/contract-call.d.ts.map +1 -1
  50. package/dist/contracts/contract-call.js +45 -54
  51. package/dist/contracts/contract-call.js.map +1 -1
  52. package/dist/contracts/contract.d.ts +24 -55
  53. package/dist/contracts/contract.d.ts.map +1 -1
  54. package/dist/contracts/contract.js +63 -101
  55. package/dist/contracts/contract.js.map +1 -1
  56. package/dist/contracts/lockup/abi.d.ts +54 -51
  57. package/dist/contracts/lockup/abi.d.ts.map +1 -1
  58. package/dist/contracts/lockup/abi.js +65 -74
  59. package/dist/contracts/lockup/abi.js.map +1 -1
  60. package/dist/contracts/lockup/helpers.d.ts +22 -18
  61. package/dist/contracts/lockup/helpers.d.ts.map +1 -1
  62. package/dist/contracts/lockup/helpers.js +44 -47
  63. package/dist/contracts/lockup/helpers.js.map +1 -1
  64. package/dist/contracts/lockup/parsers.d.ts +7 -3
  65. package/dist/contracts/lockup/parsers.d.ts.map +1 -1
  66. package/dist/contracts/lockup/parsers.js +51 -55
  67. package/dist/contracts/lockup/parsers.js.map +1 -1
  68. package/dist/contracts/lockup/storage-keys.d.ts +5 -2
  69. package/dist/contracts/lockup/storage-keys.d.ts.map +1 -1
  70. package/dist/contracts/lockup/storage-keys.js +54 -70
  71. package/dist/contracts/lockup/storage-keys.js.map +1 -1
  72. package/dist/contracts/lockup/types.d.ts +73 -70
  73. package/dist/contracts/lockup/types.d.ts.map +1 -1
  74. package/dist/contracts/lockup-prime/abi.d.ts +328 -325
  75. package/dist/contracts/lockup-prime/abi.d.ts.map +1 -1
  76. package/dist/contracts/lockup-prime/abi.js +397 -417
  77. package/dist/contracts/lockup-prime/abi.js.map +1 -1
  78. package/dist/contracts/lockup-prime/helpers.d.ts +35 -31
  79. package/dist/contracts/lockup-prime/helpers.d.ts.map +1 -1
  80. package/dist/contracts/lockup-prime/helpers.js +131 -137
  81. package/dist/contracts/lockup-prime/helpers.js.map +1 -1
  82. package/dist/contracts/lockup-prime/parsers.d.ts +9 -5
  83. package/dist/contracts/lockup-prime/parsers.d.ts.map +1 -1
  84. package/dist/contracts/lockup-prime/parsers.js +61 -61
  85. package/dist/contracts/lockup-prime/parsers.js.map +1 -1
  86. package/dist/contracts/lockup-prime/storage-keys.d.ts +7 -4
  87. package/dist/contracts/lockup-prime/storage-keys.d.ts.map +1 -1
  88. package/dist/contracts/lockup-prime/storage-keys.js +64 -80
  89. package/dist/contracts/lockup-prime/storage-keys.js.map +1 -1
  90. package/dist/contracts/lockup-prime/types.d.ts +92 -89
  91. package/dist/contracts/lockup-prime/types.d.ts.map +1 -1
  92. package/dist/contracts/lockup-prime/types.js +12 -13
  93. package/dist/contracts/lockup-prime/types.js.map +1 -1
  94. package/dist/contracts/nft/abi.d.ts +104 -0
  95. package/dist/contracts/nft/abi.d.ts.map +1 -0
  96. package/dist/contracts/nft/abi.js +135 -0
  97. package/dist/contracts/nft/abi.js.map +1 -0
  98. package/dist/contracts/nft/helpers.d.ts +21 -0
  99. package/dist/contracts/nft/helpers.d.ts.map +1 -0
  100. package/dist/contracts/nft/helpers.js +61 -0
  101. package/dist/contracts/nft/helpers.js.map +1 -0
  102. package/dist/contracts/nft/types.d.ts +47 -0
  103. package/dist/contracts/nft/types.d.ts.map +1 -0
  104. package/dist/conversion.d.ts +5 -2
  105. package/dist/conversion.d.ts.map +1 -1
  106. package/dist/conversion.js +45 -50
  107. package/dist/conversion.js.map +1 -1
  108. package/dist/crypto.d.ts +14 -16
  109. package/dist/crypto.d.ts.map +1 -1
  110. package/dist/crypto.js +121 -140
  111. package/dist/crypto.js.map +1 -1
  112. package/dist/encoding.d.ts +11 -8
  113. package/dist/encoding.d.ts.map +1 -1
  114. package/dist/encoding.js +123 -144
  115. package/dist/encoding.js.map +1 -1
  116. package/dist/encryption.d.ts +15 -12
  117. package/dist/encryption.d.ts.map +1 -1
  118. package/dist/encryption.js +119 -117
  119. package/dist/encryption.js.map +1 -1
  120. package/dist/explorer.d.ts +10 -7
  121. package/dist/explorer.d.ts.map +1 -1
  122. package/dist/explorer.js +51 -48
  123. package/dist/explorer.js.map +1 -1
  124. package/dist/formatters.d.ts +8 -5
  125. package/dist/formatters.d.ts.map +1 -1
  126. package/dist/formatters.js +67 -68
  127. package/dist/formatters.js.map +1 -1
  128. package/dist/index.d.ts +42 -55
  129. package/dist/index.js +39 -55
  130. package/dist/mnemonic.d.ts +12 -9
  131. package/dist/mnemonic.d.ts.map +1 -1
  132. package/dist/mnemonic.js +105 -114
  133. package/dist/mnemonic.js.map +1 -1
  134. package/dist/networks.d.ts +14 -17
  135. package/dist/networks.d.ts.map +1 -1
  136. package/dist/networks.js +40 -36
  137. package/dist/networks.js.map +1 -1
  138. package/dist/schemas.js +75 -79
  139. package/dist/schemas.js.map +1 -1
  140. package/dist/sdk.d.ts +69 -65
  141. package/dist/sdk.d.ts.map +1 -1
  142. package/dist/sdk.js +126 -117
  143. package/dist/sdk.js.map +1 -1
  144. package/dist/serialization.d.ts +8 -18
  145. package/dist/serialization.d.ts.map +1 -1
  146. package/dist/serialization.js +207 -260
  147. package/dist/serialization.js.map +1 -1
  148. package/dist/signing.js +67 -67
  149. package/dist/signing.js.map +1 -1
  150. package/dist/transaction-builder.d.ts +175 -184
  151. package/dist/transaction-builder.d.ts.map +1 -1
  152. package/dist/transaction-builder.js +295 -344
  153. package/dist/transaction-builder.js.map +1 -1
  154. package/dist/transaction-errors.d.ts +10 -12
  155. package/dist/transaction-errors.d.ts.map +1 -1
  156. package/dist/transaction-errors.js +145 -166
  157. package/dist/transaction-errors.js.map +1 -1
  158. package/dist/types.d.ts +530 -450
  159. package/dist/types.d.ts.map +1 -1
  160. package/dist/types.js +169 -183
  161. package/dist/types.js.map +1 -1
  162. package/dist/validation.d.ts +24 -26
  163. package/dist/validation.d.ts.map +1 -1
  164. package/dist/validation.js +194 -192
  165. package/dist/validation.js.map +1 -1
  166. package/package.json +4 -3
  167. package/dist/api/index.d.ts +0 -8
  168. package/dist/api/index.d.ts.map +0 -1
  169. package/dist/api/index.js +0 -8
  170. package/dist/api/index.js.map +0 -1
  171. package/dist/contracts/abi-types.js +0 -8
  172. package/dist/contracts/abi-types.js.map +0 -1
  173. package/dist/contracts/index.d.ts +0 -7
  174. package/dist/contracts/index.d.ts.map +0 -1
  175. package/dist/contracts/index.js +0 -7
  176. package/dist/contracts/index.js.map +0 -1
  177. package/dist/contracts/lockup/calls.d.ts +0 -23
  178. package/dist/contracts/lockup/calls.d.ts.map +0 -1
  179. package/dist/contracts/lockup/calls.js +0 -25
  180. package/dist/contracts/lockup/calls.js.map +0 -1
  181. package/dist/contracts/lockup/index.d.ts +0 -6
  182. package/dist/contracts/lockup/index.d.ts.map +0 -1
  183. package/dist/contracts/lockup/index.js +0 -6
  184. package/dist/contracts/lockup/index.js.map +0 -1
  185. package/dist/contracts/lockup/types.js +0 -7
  186. package/dist/contracts/lockup/types.js.map +0 -1
  187. package/dist/contracts/lockup-prime/calls.d.ts +0 -53
  188. package/dist/contracts/lockup-prime/calls.d.ts.map +0 -1
  189. package/dist/contracts/lockup-prime/calls.js +0 -60
  190. package/dist/contracts/lockup-prime/calls.js.map +0 -1
  191. package/dist/contracts/lockup-prime/index.d.ts +0 -6
  192. package/dist/contracts/lockup-prime/index.d.ts.map +0 -1
  193. package/dist/contracts/lockup-prime/index.js +0 -6
  194. package/dist/contracts/lockup-prime/index.js.map +0 -1
  195. package/dist/index.d.ts.map +0 -1
  196. package/dist/index.js.map +0 -1
  197. package/dist/schemas.d.ts +0 -67
  198. package/dist/schemas.d.ts.map +0 -1
  199. package/dist/signing.d.ts +0 -39
  200. package/dist/signing.d.ts.map +0 -1
package/README.md CHANGED
@@ -20,6 +20,19 @@ pnpm add @amadeus-protocol/sdk
20
20
  bun add @amadeus-protocol/sdk
21
21
  ```
22
22
 
23
+ > **ESM-only**: this package is published as pure ESM (`"type": "module"`). Use Node.js 20+ with `"type": "module"` in your `package.json`, or any modern bundler (Vite, webpack, esbuild, Metro). For CommonJS consumers, run via [`tsx`](https://github.com/privatenumber/tsx). See [Troubleshooting](https://docs.ama.one/sdk/9.-troubleshooting.md) for the `1.0.x` `ERR_MODULE_NOT_FOUND` issue and upgrade path.
24
+
25
+ ## What's New in 1.1.0
26
+
27
+ - **`contract.view()`** — read-only contract execution
28
+ - **`chain.getByFilter()`** / **`chain.getKpi()`** — filtered tx queries + protocol KPIs
29
+ - **`proof.getContractStateProof()`** — merkle proofs for contract state
30
+ - **`submitAndWait(txPacked, { finalized: true })`** — wait for finality instead of confirmation
31
+ - **NFT contract** — `NFT_ABI`, `buildNftTransfer/Mint/CreateCollection`, `TransactionBuilder.nftTransfer/nftMint/nftCreateCollection`
32
+ - **ESM fix** — published `dist/*.js` now resolves correctly under raw `node` (the `1.0.x` `ERR_MODULE_NOT_FOUND` bug)
33
+
34
+ See the [CHANGELOG](./CHANGELOG.md) for full release history.
35
+
23
36
  ## Features
24
37
 
25
38
  - **Canonical Serialization (VecPack)**: Deterministic encoding/decoding for cryptographic operations
@@ -72,6 +85,8 @@ const sdk = new AmadeusSDK({
72
85
  const stats = await sdk.chain.getStats()
73
86
  const tip = await sdk.chain.getTip()
74
87
  const entry = await sdk.chain.getByHash('5Kd3N...')
88
+ const { txs, cursor } = await sdk.chain.getByFilter({ contract: 'Coin', function: 'transfer' })
89
+ const { kpi } = await sdk.chain.getKpi()
75
90
 
76
91
  // Wallet API
77
92
  const balance = await sdk.wallet.getBalance('5Kd3N...', 'AMA')
@@ -79,12 +94,18 @@ const allBalances = await sdk.wallet.getAllBalances('5Kd3N...')
79
94
 
80
95
  // Transaction API
81
96
  const result = await sdk.transaction.submit(txPacked)
82
- const resultWithWait = await sdk.transaction.submitAndWait(txPacked)
97
+ const confirmed = await sdk.transaction.submitAndWait(txPacked)
98
+ const finalized = await sdk.transaction.submitAndWait(txPacked, { finalized: true })
83
99
  const tx = await sdk.transaction.get('5Kd3N...')
84
100
 
85
101
  // Contract API
86
102
  const contractData = await sdk.contract.get(key)
87
103
  const richlist = await sdk.contract.getRichlist()
104
+ const { success, result } = await sdk.contract.view({
105
+ contract: 'LockupPrime',
106
+ function: 'view_balance',
107
+ args: ['my_vault']
108
+ })
88
109
 
89
110
  // Epoch API
90
111
  const scores = await sdk.epoch.getScore()
@@ -93,6 +114,10 @@ const emission = await sdk.epoch.getEmissionAddress('5Kd3N...')
93
114
  // Peer API
94
115
  const nodes = await sdk.peer.getNodes()
95
116
  const trainers = await sdk.peer.getTrainers()
117
+
118
+ // Proof API
119
+ const validatorProof = await sdk.proof.getValidators(entryHash)
120
+ const stateProof = await sdk.proof.getContractStateProof(stateKey)
96
121
  ```
97
122
 
98
123
  ### Key Generation
@@ -151,6 +176,137 @@ const { txHash, txPacked } = builder.buildAndSign('Coin', 'transfer', [
151
176
  ])
152
177
  ```
153
178
 
179
+ #### ABI-Driven (Lockup, LockupPrime, etc.)
180
+
181
+ The recommended pattern for built-in contracts. Pass any ABI to `builder.contract(abi)` and get fully-typed function calls:
182
+
183
+ ```typescript
184
+ import {
185
+ TransactionBuilder,
186
+ LOCKUP_PRIME_ABI,
187
+ LOCKUP_ABI,
188
+ toAtomicAma
189
+ } from '@amadeus-protocol/sdk'
190
+
191
+ const builder = new TransactionBuilder('5Kd3N...')
192
+
193
+ // LockupPrime — auto-typed methods derived from the ABI
194
+ builder.contract(LOCKUP_PRIME_ABI).lock({ amount: toAtomicAma(100).toString(), tier: '30d' })
195
+ builder.contract(LOCKUP_PRIME_ABI).unlock({ vaultIndex: '3' })
196
+ builder.contract(LOCKUP_PRIME_ABI).daily_checkin({ vaultIndex: '7' })
197
+
198
+ // Lockup
199
+ builder.contract(LOCKUP_ABI).unlock({ vaultIndex: '5' })
200
+ ```
201
+
202
+ #### NFT (transfer, mint, create_collection)
203
+
204
+ The `Nft` built-in contract has dedicated builder methods. NFT amounts are integer counts, **not** AMA atomic units.
205
+
206
+ ```typescript
207
+ const builder = new TransactionBuilder(privateKey)
208
+
209
+ // Create a collection (caller becomes owner)
210
+ builder.nftCreateCollection({ collection: 'AGENTIC', soulbound: false })
211
+
212
+ // Mint tokens (collection owner only)
213
+ builder.nftMint({ recipient: '5Kd3N...', amount: 10, collection: 'AGENTIC', token: '1' })
214
+
215
+ // Transfer
216
+ builder.nftTransfer({ recipient: '5Kd3N...', amount: 1, collection: 'AGENTIC', token: '1' })
217
+ ```
218
+
219
+ Static variants: `TransactionBuilder.buildSignedNftTransfer/Mint/CreateCollection(input)` — each takes the same params plus `senderPrivkey`.
220
+
221
+ ### Signing Transactions
222
+
223
+ The SDK supports two patterns. Pick whichever fits your workflow.
224
+
225
+ #### Pattern 1 — Auto-signed (high-level, recommended)
226
+
227
+ The `TransactionBuilder` instance methods build **and** sign in one call. Best for app code where you have the private key in hand.
228
+
229
+ ```typescript
230
+ import { TransactionBuilder, LOCKUP_PRIME_ABI, toAtomicAma } from '@amadeus-protocol/sdk'
231
+
232
+ const builder = new TransactionBuilder('5Kd3N...') // Base58 seed
233
+
234
+ // Coin transfer
235
+ const a = builder.transfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })
236
+
237
+ // ABI-driven (any contract)
238
+ const b = builder.contract(LOCKUP_PRIME_ABI).lock({
239
+ amount: toAtomicAma(100).toString(),
240
+ tier: '30d'
241
+ })
242
+
243
+ // NFT
244
+ const c = builder.nftTransfer({
245
+ recipient: '5Kd3N...',
246
+ amount: 1,
247
+ collection: 'AGENTIC',
248
+ token: '1'
249
+ })
250
+
251
+ // All return { txHash, txPacked } ready for sdk.transaction.submit(txPacked)
252
+ ```
253
+
254
+ #### Pattern 2 — Manual: build a `ContractCall`, sign separately
255
+
256
+ Build a `ContractCall` with a standalone helper or `createContract(ABI)`, then sign it independently with `TransactionBuilder.signCall(privkey, call)`. Useful when:
257
+
258
+ - You want to inspect or log the call before signing
259
+ - The signing key lives somewhere else (HSM, separate process, separate machine)
260
+ - You want to batch-build and sign at the end
261
+
262
+ ```typescript
263
+ import {
264
+ TransactionBuilder,
265
+ createContract,
266
+ LOCKUP_PRIME_ABI,
267
+ buildCoinTransfer,
268
+ buildNftTransfer,
269
+ toAtomicAma
270
+ } from '@amadeus-protocol/sdk'
271
+
272
+ // Build a ContractCall — three ways:
273
+
274
+ // A. Standalone helper (Coin)
275
+ const callA = buildCoinTransfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })
276
+
277
+ // B. Standalone helper (NFT)
278
+ const callB = buildNftTransfer({
279
+ recipient: '5Kd3N...',
280
+ amount: 1,
281
+ collection: 'AGENTIC',
282
+ token: '1'
283
+ })
284
+
285
+ // C. ABI-driven, any contract
286
+ const lockupPrime = createContract(LOCKUP_PRIME_ABI)
287
+ const callC = lockupPrime.lock({ amount: toAtomicAma(100).toString(), tier: '30d' })
288
+
289
+ // Inspect if you want
290
+ console.log('Will call:', callC.contract, callC.method, callC.args)
291
+
292
+ // Sign with any private key (no builder instance needed)
293
+ const { txHash, txPacked } = TransactionBuilder.signCall('5Kd3N...', callC)
294
+ ```
295
+
296
+ #### Build-unsigned-then-sign (debugging)
297
+
298
+ If you need to inspect the full unsigned transaction (nonce, signer, action) before signing:
299
+
300
+ ```typescript
301
+ const builder = new TransactionBuilder('5Kd3N...')
302
+
303
+ const unsigned = builder.buildTransfer({ recipient: '5Kd3N...', amount: 10.5, symbol: 'AMA' })
304
+ console.log('Nonce:', unsigned.tx.nonce)
305
+ console.log('Action:', unsigned.tx.action)
306
+
307
+ const { txHash, txPacked } = builder.sign(unsigned)
308
+ ```
309
+
154
310
  #### Using Static Methods
155
311
 
156
312
  ```typescript
@@ -229,22 +385,19 @@ const atomic = toAtomicAma(1.5) // Returns 1500000000
229
385
  const ama = fromAtomicAma(1500000000) // Returns 1.5
230
386
  ```
231
387
 
232
- ### Signing Transactions
388
+ ### Mnemonics (BIP39)
233
389
 
234
390
  ```typescript
235
- import { TransactionBuilder } from '@amadeus-protocol/sdk'
391
+ import { generateMnemonic, validateMnemonic, mnemonicToSeedBase58 } from '@amadeus-protocol/sdk'
236
392
 
237
- // Using TransactionBuilder instance
238
- const builder = new TransactionBuilder('5Kd3N...')
239
-
240
- // Build unsigned transaction
241
- const unsignedTx = builder.build('Coin', 'transfer', args)
393
+ // Generate a 12-word mnemonic
394
+ const mnemonic = generateMnemonic()
242
395
 
243
- // Sign the transaction
244
- const { txHash, txPacked } = builder.sign(unsignedTx)
245
-
246
- // Or build and sign in one step
247
- const { txHash, txPacked } = builder.buildAndSign('Coin', 'transfer', args)
396
+ // Validate a mnemonic
397
+ if (validateMnemonic(mnemonic)) {
398
+ // Derive a Base58 seed (compatible with TransactionBuilder)
399
+ const seedBase58 = mnemonicToSeedBase58(mnemonic)
400
+ }
248
401
  ```
249
402
 
250
403
  ### Encoding Utilities
@@ -300,6 +453,13 @@ const decrypted = await decryptWithPassword(encrypted, 'my-password')
300
453
  - `derivePublicKeyFromSeedBase58(base58Seed: string): string` - Derive public key from Base58 seed
301
454
  - `deriveSkAndSeed64FromBase58Seed(base58Seed64: string)` - Derive secret key and seed
302
455
 
456
+ ### Mnemonics (BIP39)
457
+
458
+ - `generateMnemonic(): string` - Generate a 12-word BIP39 mnemonic
459
+ - `validateMnemonic(mnemonic: string): boolean` - Validate a BIP39 mnemonic
460
+ - `mnemonicToSeedBase58(mnemonic: string): string` - Derive a Base58 seed from a mnemonic
461
+ - `encodeVaultSecret`, `decodeVaultSecret`, `detectInputType` - Vault helpers
462
+
303
463
  ### Encoding
304
464
 
305
465
  - `toBase58(buf: Uint8Array): string` - Encode bytes to Base58
@@ -311,11 +471,6 @@ const decrypted = await decryptWithPassword(encrypted, 'my-password')
311
471
  - `uint8ArrayToArrayBuffer(bytes: Uint8Array): ArrayBuffer` - Convert Uint8Array to ArrayBuffer
312
472
  - `arrayBufferToUint8Array(buffer: ArrayBuffer): Uint8Array` - Convert ArrayBuffer to Uint8Array
313
473
 
314
- ### Signing
315
-
316
- - `signTx(hash: Uint8Array, sk: PrivKey): Uint8Array` - Sign a transaction hash
317
- - `signOOB(sk: string, msg: Uint8Array): Uint8Array` - Sign an out-of-band message
318
-
319
474
  ### Conversion
320
475
 
321
476
  - `toAtomicAma(ama: number): number` - Convert AMA to atomic units
@@ -333,18 +488,48 @@ const decrypted = await decryptWithPassword(encrypted, 'my-password')
333
488
 
334
489
  - `TransactionBuilder` - Class for building and signing transactions
335
490
  - **Constructor:** `new TransactionBuilder(privateKey?: string)` - Create a new builder instance
336
- - **Instance Methods:**
337
- - `build(contract, method, args, signerPk?): UnsignedTransactionWithHash` - Build an unsigned transaction
338
- - `sign(unsignedTx, signerSk?): BuildTxResult` - Sign an unsigned transaction
339
- - `buildAndSign(contract, method, args, signerPk?, signerSk?): BuildTxResult` - Build and sign in one step
340
- - `buildTransfer(input, signerPk?): UnsignedTransactionWithHash` - Build an unsigned transfer
341
- - `transfer(input): BuildTxResult` - Build and sign a transfer (convenience)
342
- - **Static Methods:**
343
- - `build(signerPk, contract, method, args): UnsignedTransactionWithHash` - Build unsigned transaction
344
- - `sign(unsignedTx, signerSk): BuildTxResult` - Sign an unsigned transaction
345
- - `buildAndSign(signerPk, signerSk, contract, method, args): BuildTxResult` - Build and sign in one step
346
- - `buildTransfer(input, signerPk): UnsignedTransactionWithHash` - Build unsigned transfer
347
- - `buildSignedTransfer(input): BuildTxResult` - Build and sign transfer (convenience)
491
+ - **ABI-driven (recommended):**
492
+ - `contract(abi)` - Returns a typed, signer-bound contract interface; each ABI function becomes a method that builds and signs in one step
493
+ - **Generic instance methods:**
494
+ - `build(contract, method, args, signerPk?): UnsignedTransactionWithHash`
495
+ - `sign(unsignedTx, signerSk?): BuildTransactionResult`
496
+ - `buildAndSign(contract, method, args, signerPk?, signerSk?): BuildTransactionResult`
497
+ - `buildFromCall(call): UnsignedTransactionWithHash`
498
+ - `buildAndSignCall(call): BuildTransactionResult`
499
+ - **Coin transfer:**
500
+ - `buildTransfer(input, signerPk?): UnsignedTransactionWithHash`
501
+ - `transfer(input): BuildTransactionResult`
502
+ - **NFT (Nft contract):**
503
+ - `nftTransfer({ recipient, amount, collection, token }): BuildTransactionResult`
504
+ - `nftMint({ recipient, amount, collection, token }): BuildTransactionResult`
505
+ - `nftCreateCollection({ collection, soulbound? }): BuildTransactionResult`
506
+ - **Lockup / LockupPrime convenience methods:**
507
+ - `lockupUnlock({ vaultIndex }): BuildTransactionResult`
508
+ - `lockupPrimeLock({ amount, tier }): BuildTransactionResult`
509
+ - `lockupPrimeUnlock({ vaultIndex }): BuildTransactionResult`
510
+ - `lockupPrimeDailyCheckin({ vaultIndex }): BuildTransactionResult`
511
+ - **Static methods:** `signCall`, `buildFromCall`, `buildAndSignCall`, `buildSignedTransfer`, `buildSignedNft{Transfer,Mint,CreateCollection}`, `buildSignedLockup{Unlock}`, `buildSignedLockupPrime{Lock,Unlock,DailyCheckin}`
512
+
513
+ ### Contract ABIs
514
+
515
+ `as const` ABI definitions for built-in contracts. Pass any ABI to `createContract(abi)` or `builder.contract(abi)` for fully-typed function calls.
516
+
517
+ - `LOCKUP_ABI` - `Lockup` (vesting) — `unlock(vaultIndex)`
518
+ - `LOCKUP_PRIME_ABI` - `LockupPrime` — `lock(amount, tier)`, `unlock(vaultIndex)`, `daily_checkin(vaultIndex)`
519
+ - `NFT_ABI` - `Nft` — `transfer`, `mint`, `create_collection`
520
+
521
+ Standalone builders that return a `ContractCall`:
522
+
523
+ - `buildCoinTransfer({ recipient, amount, symbol })`
524
+ - `buildNftTransfer({ recipient, amount, collection, token })`
525
+ - `buildNftMint({ recipient, amount, collection, token })`
526
+ - `buildNftCreateCollection({ collection, soulbound? })`
527
+ - `createContract(abi).fn(params)` - generic ABI-driven builder
528
+ - `buildContractCall(abi, fn, params)` - lower-level ABI-driven builder
529
+
530
+ ### Full API Reference
531
+
532
+ For complete documentation including request/response types, error handling, and end-to-end examples, see [docs.ama.one/sdk](https://docs.ama.one/sdk/1.-introduction.md).
348
533
 
349
534
  ## Examples
350
535
 
@@ -1,119 +1,146 @@
1
- /**
2
- * Chain API
3
- *
4
- * Provides methods for querying blockchain data
5
- */
6
- import type { AmadeusClient } from '../client';
7
- import type { TransactionFilters, GetTipResponse, GetStatsResponse, GetByHashResponse, GetByHeightResponse, GetTransactionsInEntryResponse, GetTransactionEventsByAccountResponse, Transaction } from '../types';
8
- export declare class ChainAPI {
9
- private client;
10
- constructor(client: AmadeusClient);
11
- /**
12
- * Get the current chain tip (latest entry)
13
- *
14
- * @returns Promise resolving to the latest chain entry
15
- *
16
- * @example
17
- * ```ts
18
- * const { entry } = await sdk.chain.getTip()
19
- * console.log('Current height:', entry.height)
20
- * ```
21
- */
22
- getTip(): Promise<GetTipResponse>;
23
- /**
24
- * Get chain statistics
25
- *
26
- * @returns Promise resolving to chain statistics
27
- *
28
- * @example
29
- * ```ts
30
- * const { stats } = await sdk.chain.getStats()
31
- * console.log('Total entries:', stats.total_entries)
32
- * ```
33
- */
34
- getStats(): Promise<GetStatsResponse>;
35
- /**
36
- * Get entry by hash
37
- *
38
- * @param hash - Entry hash (Base58 encoded)
39
- * @param filterOnFunction - Optional function filter
40
- * @returns Promise resolving to chain entry
41
- * @throws {Error} If hash is invalid
42
- *
43
- * @example
44
- * ```ts
45
- * const { entry } = await sdk.chain.getByHash('5Kd3N...')
46
- * ```
47
- */
48
- getByHash(hash: string, filterOnFunction?: string): Promise<GetByHashResponse>;
49
- /**
50
- * Get entries by height
51
- *
52
- * @param height - Block height (must be >= 0)
53
- * @returns Promise resolving to chain entries at the specified height
54
- * @throws {Error} If height is invalid
55
- *
56
- * @example
57
- * ```ts
58
- * const { entries } = await sdk.chain.getByHeight(1000)
59
- * ```
60
- */
61
- getByHeight(height: number): Promise<GetByHeightResponse>;
62
- /**
63
- * Get entries by height with transactions
64
- *
65
- * @param height - Block height (must be >= 0)
66
- * @returns Promise resolving to chain entries with transactions at the specified height
67
- * @throws {Error} If height is invalid
68
- *
69
- * @example
70
- * ```ts
71
- * const { entries } = await sdk.chain.getByHeightWithTxs(1000)
72
- * ```
73
- */
74
- getByHeightWithTxs(height: number): Promise<GetByHeightResponse>;
75
- /**
76
- * Get a specific transaction by ID
77
- *
78
- * @param txid - Transaction ID (Base58 encoded)
79
- * @returns Promise resolving to transaction data
80
- * @throws {Error} If transaction ID is invalid
81
- *
82
- * @example
83
- * ```ts
84
- * const tx = await sdk.chain.getTransaction('5Kd3N...')
85
- * ```
86
- */
87
- getTransaction(txid: string): Promise<Transaction>;
88
- /**
89
- * Get transactions in a specific entry
90
- *
91
- * @param entryHash - Entry hash (Base58 encoded)
92
- * @returns Promise resolving to transactions in the entry
93
- * @throws {Error} If entry hash is invalid
94
- *
95
- * @example
96
- * ```ts
97
- * const { txs } = await sdk.chain.getTransactionsInEntry('5Kd3N...')
98
- * ```
99
- */
100
- getTransactionsInEntry(entryHash: string): Promise<GetTransactionsInEntryResponse>;
101
- /**
102
- * Get transaction events by account with filtering
103
- *
104
- * @param account - Account address (Base58 encoded)
105
- * @param filters - Optional filters for transactions
106
- * @returns Promise resolving to transaction events
107
- * @throws {Error} If account address is invalid
108
- *
109
- * @example
110
- * ```ts
111
- * const { txs, cursor } = await sdk.chain.getTransactionEventsByAccount('5Kd3N...', {
112
- * limit: 10,
113
- * sort: 'desc'
114
- * })
115
- * ```
116
- */
117
- getTransactionEventsByAccount(account: string, filters?: TransactionFilters): Promise<GetTransactionEventsByAccountResponse>;
1
+ import { GetByHashResponse, GetByHeightResponse, GetKpiResponse, GetStatsResponse, GetTipResponse, GetTransactionEventsByAccountResponse, GetTransactionsInEntryResponse, Transaction, TransactionFilters, TxByFilterParams, TxByFilterResponse } from "../types.js";
2
+ import { AmadeusClient } from "../client.js";
3
+
4
+ //#region src/api/chain.d.ts
5
+ declare class ChainAPI {
6
+ private client;
7
+ constructor(client: AmadeusClient);
8
+ /**
9
+ * Get the current chain tip (latest entry)
10
+ *
11
+ * @returns Promise resolving to the latest chain entry
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * const { entry } = await sdk.chain.getTip()
16
+ * console.log('Current height:', entry.height)
17
+ * ```
18
+ */
19
+ getTip(): Promise<GetTipResponse>;
20
+ /**
21
+ * Get chain statistics
22
+ *
23
+ * @returns Promise resolving to chain statistics
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * const { stats } = await sdk.chain.getStats()
28
+ * console.log('Total entries:', stats.total_entries)
29
+ * ```
30
+ */
31
+ getStats(): Promise<GetStatsResponse>;
32
+ /**
33
+ * Get entry by hash
34
+ *
35
+ * @param hash - Entry hash (Base58 encoded)
36
+ * @param filterOnFunction - Optional function filter
37
+ * @returns Promise resolving to chain entry
38
+ * @throws {Error} If hash is invalid
39
+ *
40
+ * @example
41
+ * ```ts
42
+ * const { entry } = await sdk.chain.getByHash('5Kd3N...')
43
+ * ```
44
+ */
45
+ getByHash(hash: string, filterOnFunction?: string): Promise<GetByHashResponse>;
46
+ /**
47
+ * Get entries by height
48
+ *
49
+ * @param height - Block height (must be >= 0)
50
+ * @returns Promise resolving to chain entries at the specified height
51
+ * @throws {Error} If height is invalid
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * const { entries } = await sdk.chain.getByHeight(1000)
56
+ * ```
57
+ */
58
+ getByHeight(height: number): Promise<GetByHeightResponse>;
59
+ /**
60
+ * Get entries by height with transactions
61
+ *
62
+ * @param height - Block height (must be >= 0)
63
+ * @returns Promise resolving to chain entries with transactions at the specified height
64
+ * @throws {Error} If height is invalid
65
+ *
66
+ * @example
67
+ * ```ts
68
+ * const { entries } = await sdk.chain.getByHeightWithTxs(1000)
69
+ * ```
70
+ */
71
+ getByHeightWithTxs(height: number): Promise<GetByHeightResponse>;
72
+ /**
73
+ * Get a specific transaction by ID
74
+ *
75
+ * @param txid - Transaction ID (Base58 encoded)
76
+ * @returns Promise resolving to transaction data
77
+ * @throws {Error} If transaction ID is invalid
78
+ *
79
+ * @example
80
+ * ```ts
81
+ * const tx = await sdk.chain.getTransaction('5Kd3N...')
82
+ * ```
83
+ */
84
+ getTransaction(txid: string): Promise<Transaction>;
85
+ /**
86
+ * Get transactions in a specific entry
87
+ *
88
+ * @param entryHash - Entry hash (Base58 encoded)
89
+ * @returns Promise resolving to transactions in the entry
90
+ * @throws {Error} If entry hash is invalid
91
+ *
92
+ * @example
93
+ * ```ts
94
+ * const { txs } = await sdk.chain.getTransactionsInEntry('5Kd3N...')
95
+ * ```
96
+ */
97
+ getTransactionsInEntry(entryHash: string): Promise<GetTransactionsInEntryResponse>;
98
+ /**
99
+ * Get transaction events by account with filtering
100
+ *
101
+ * @param account - Account address (Base58 encoded)
102
+ * @param filters - Optional filters for transactions
103
+ * @returns Promise resolving to transaction events
104
+ * @throws {Error} If account address is invalid
105
+ *
106
+ * @example
107
+ * ```ts
108
+ * const { txs, cursor } = await sdk.chain.getTransactionEventsByAccount('5Kd3N...', {
109
+ * limit: 10,
110
+ * sort: 'desc'
111
+ * })
112
+ * ```
113
+ */
114
+ getTransactionEventsByAccount(account: string, filters?: TransactionFilters): Promise<GetTransactionEventsByAccountResponse>;
115
+ /**
116
+ * Query transactions by arbitrary filter (signer, receiver, contract, function).
117
+ *
118
+ * All filter fields are optional; provide only the ones you want to constrain.
119
+ * Returns a cursor for pagination — pass it back as `cursor` in a subsequent call.
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * const { txs, cursor } = await sdk.chain.getByFilter({
124
+ * signer: '5Kd3N...',
125
+ * contract: 'Coin',
126
+ * function: 'transfer',
127
+ * limit: 50,
128
+ * sort: 'desc'
129
+ * })
130
+ * ```
131
+ */
132
+ getByFilter(filters?: TxByFilterParams): Promise<TxByFilterResponse>;
133
+ /**
134
+ * Get protocol-level KPIs (burned, fees, active validators/peers, total tx, UAW, etc.).
135
+ *
136
+ * @example
137
+ * ```ts
138
+ * const { kpi } = await sdk.chain.getKpi()
139
+ * console.log('Total tx:', kpi.total_tx)
140
+ * ```
141
+ */
142
+ getKpi(): Promise<GetKpiResponse>;
118
143
  }
144
+ //#endregion
145
+ export { ChainAPI };
119
146
  //# sourceMappingURL=chain.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/api/chain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EACX,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,8BAA8B,EAC9B,qCAAqC,EACrC,WAAW,EACX,MAAM,UAAU,CAAA;AAKjB,qBAAa,QAAQ;IACR,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEzC;;;;;;;;;;OAUG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIvC;;;;;;;;;;OAUG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAI3C;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOpF;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAK/D;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAKtE;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKxD;;;;;;;;;;;OAWG;IACG,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAOxF;;;;;;;;;;;;;;;OAeG;IACG,6BAA6B,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC9B,OAAO,CAAC,qCAAqC,CAAC;CASjD"}
1
+ {"version":3,"file":"chain.d.ts","names":[],"sources":["../../src/api/chain.ts"],"mappings":";;;;cAwBa,QAAA;EAAA,QACQ,MAAA;cAAA,MAAA,EAAQ,aAAA;EA4BF;;;;;;;;;;;EAfpB,MAAA,CAAA,GAAU,OAAA,CAAQ,cAAA;EA+Hd;;;;;;;;;;;EAhHJ,QAAA,CAAA,GAAY,OAAA,CAAQ,gBAAA;EA5BE;;;;;;;;;;;;;EA6CtB,SAAA,CAAU,IAAA,UAAc,gBAAA,YAA4B,OAAA,CAAQ,iBAAA;EAmBhD;;;;;;;;;;;;EAAZ,WAAA,CAAY,MAAA,WAAiB,OAAA,CAAQ,mBAAA;EAmDM;;;;;;;;;;;;EAlC3C,kBAAA,CAAmB,MAAA,WAAiB,OAAA,CAAQ,mBAAA;EAuG5C;;;;;;;;;;;;EAtFA,cAAA,CAAe,IAAA,WAAe,OAAA,CAAQ,WAAA;;;;;;;;;;;;;EAiBtC,sBAAA,CAAuB,SAAA,WAAoB,OAAA,CAAQ,8BAAA;;;;;;;;;;;;;;;;;EAuBnD,6BAAA,CACL,OAAA,UACA,OAAA,GAAS,kBAAA,GACP,OAAA,CAAQ,qCAAA;;;;;;;;;;;;;;;;;;EA2BL,WAAA,CAAY,OAAA,GAAS,gBAAA,GAAwB,OAAA,CAAQ,kBAAA;;;;;;;;;;EAgBrD,MAAA,CAAA,GAAU,OAAA,CAAQ,cAAA;AAAA"}