@thru/programs 0.3.4 → 0.3.6

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 (152) hide show
  1. package/README.md +124 -39
  2. package/dist/abi-manager/index.cjs +9568 -0
  3. package/dist/abi-manager/index.cjs.map +1 -0
  4. package/dist/abi-manager/index.d.cts +2169 -0
  5. package/dist/abi-manager/index.d.ts +2169 -0
  6. package/dist/abi-manager/index.js +4 -0
  7. package/dist/abi-manager/index.js.map +1 -0
  8. package/dist/amm/index.cjs +132 -33
  9. package/dist/amm/index.cjs.map +1 -1
  10. package/dist/amm/index.d.cts +1 -1
  11. package/dist/amm/index.d.ts +1 -1
  12. package/dist/amm/index.js +5 -2
  13. package/dist/amm/index.js.map +1 -1
  14. package/dist/bootstrap-addresses/index.cjs +118 -0
  15. package/dist/bootstrap-addresses/index.cjs.map +1 -0
  16. package/dist/bootstrap-addresses/index.d.cts +44 -0
  17. package/dist/bootstrap-addresses/index.d.ts +44 -0
  18. package/dist/bootstrap-addresses/index.js +5 -0
  19. package/dist/bootstrap-addresses/index.js.map +1 -0
  20. package/dist/chunk-6IC6CO5S.js +9443 -0
  21. package/dist/chunk-6IC6CO5S.js.map +1 -0
  22. package/dist/chunk-7DHFYBRW.js +51 -0
  23. package/dist/chunk-7DHFYBRW.js.map +1 -0
  24. package/dist/chunk-7FBCBZIY.js +41 -0
  25. package/dist/chunk-7FBCBZIY.js.map +1 -0
  26. package/dist/chunk-BNYDH4ZP.js +4351 -0
  27. package/dist/chunk-BNYDH4ZP.js.map +1 -0
  28. package/dist/{chunk-J7B7XYOI.js → chunk-CYG4PB65.js} +14 -41
  29. package/dist/chunk-CYG4PB65.js.map +1 -0
  30. package/dist/chunk-VNTPD4AR.js +37 -0
  31. package/dist/chunk-VNTPD4AR.js.map +1 -0
  32. package/dist/chunk-YX7BLFQZ.js +81 -0
  33. package/dist/chunk-YX7BLFQZ.js.map +1 -0
  34. package/dist/chunk-ZHF2PH5H.js +6536 -0
  35. package/dist/chunk-ZHF2PH5H.js.map +1 -0
  36. package/dist/clob/index.cjs +8461 -4922
  37. package/dist/clob/index.cjs.map +1 -1
  38. package/dist/clob/index.d.cts +1115 -53
  39. package/dist/clob/index.d.ts +1115 -53
  40. package/dist/clob/index.js +6817 -3395
  41. package/dist/clob/index.js.map +1 -1
  42. package/dist/deploy/index.cjs +24751 -0
  43. package/dist/deploy/index.cjs.map +1 -0
  44. package/dist/deploy/index.d.cts +180 -0
  45. package/dist/deploy/index.d.ts +180 -0
  46. package/dist/deploy/index.js +1849 -0
  47. package/dist/deploy/index.js.map +1 -0
  48. package/dist/helpers-DD7q61nr.d.cts +7 -0
  49. package/dist/helpers-DD7q61nr.d.ts +7 -0
  50. package/dist/manager/index.cjs +6680 -0
  51. package/dist/manager/index.cjs.map +1 -0
  52. package/dist/manager/index.d.cts +1279 -0
  53. package/dist/manager/index.d.ts +1279 -0
  54. package/dist/manager/index.js +5 -0
  55. package/dist/manager/index.js.map +1 -0
  56. package/dist/multicall/index.cjs +117 -40
  57. package/dist/multicall/index.cjs.map +1 -1
  58. package/dist/multicall/index.d.cts +5 -2
  59. package/dist/multicall/index.d.ts +5 -2
  60. package/dist/multicall/index.js +4 -1
  61. package/dist/oracle/index.cjs +122 -14
  62. package/dist/oracle/index.cjs.map +1 -1
  63. package/dist/oracle/index.d.cts +3 -1
  64. package/dist/oracle/index.d.ts +3 -1
  65. package/dist/oracle/index.js +7 -1
  66. package/dist/oracle/index.js.map +1 -1
  67. package/dist/passkey-manager/index.cjs +107 -6
  68. package/dist/passkey-manager/index.cjs.map +1 -1
  69. package/dist/passkey-manager/index.d.cts +1 -1
  70. package/dist/passkey-manager/index.d.ts +1 -1
  71. package/dist/passkey-manager/index.js +6 -3
  72. package/dist/passkey-manager/index.js.map +1 -1
  73. package/dist/uploader/index.cjs +4442 -0
  74. package/dist/uploader/index.cjs.map +1 -0
  75. package/dist/uploader/index.d.cts +761 -0
  76. package/dist/uploader/index.d.ts +761 -0
  77. package/dist/uploader/index.js +4 -0
  78. package/dist/uploader/index.js.map +1 -0
  79. package/package.json +27 -2
  80. package/src/abi-manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
  81. package/src/abi-manager/abi/thru/common/primitives/types.ts +2428 -0
  82. package/src/abi-manager/abi/thru/program/abi_manager/types.ts +7037 -0
  83. package/src/abi-manager/accounts.ts +91 -0
  84. package/src/abi-manager/constants.ts +19 -0
  85. package/src/abi-manager/derivation.ts +86 -0
  86. package/src/abi-manager/errors.ts +48 -0
  87. package/src/abi-manager/index.test.ts +136 -0
  88. package/src/abi-manager/index.ts +56 -0
  89. package/src/abi-manager/instructions.ts +573 -0
  90. package/src/abi-manager/types.ts +150 -0
  91. package/src/amm/index.test.ts +2 -6
  92. package/src/amm/index.ts +2 -2
  93. package/src/bootstrap-addresses/index.test.ts +59 -0
  94. package/src/bootstrap-addresses/index.ts +58 -0
  95. package/src/clob/abi/thru/program/clob/types.ts +6981 -3070
  96. package/src/clob/exchange-client.test.ts +115 -2
  97. package/src/clob/exchange-client.ts +52 -13
  98. package/src/clob/exchange.test.ts +18 -16
  99. package/src/clob/exchange.ts +4 -0
  100. package/src/clob/index.test.ts +140 -7
  101. package/src/clob/index.ts +304 -12
  102. package/src/clob/price.test.ts +32 -0
  103. package/src/clob/price.ts +77 -0
  104. package/src/deploy/accounts.ts +208 -0
  105. package/src/deploy/chain.ts +163 -0
  106. package/src/deploy/constants.ts +30 -0
  107. package/src/deploy/deploy.test.ts +349 -0
  108. package/src/deploy/errors.ts +72 -0
  109. package/src/deploy/index.ts +44 -0
  110. package/src/deploy/inspection.ts +146 -0
  111. package/src/deploy/seeds.ts +29 -0
  112. package/src/deploy/types.ts +178 -0
  113. package/src/deploy/uploader.test.ts +326 -0
  114. package/src/deploy/uploader.ts +558 -0
  115. package/src/deploy/validation-imports.test.ts +55 -0
  116. package/src/deploy/validation.ts +183 -0
  117. package/src/deploy/workflows.test.ts +422 -0
  118. package/src/deploy/workflows.ts +1088 -0
  119. package/src/helpers/bytes.test.ts +58 -0
  120. package/src/helpers/bytes.ts +28 -3
  121. package/src/manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
  122. package/src/manager/abi/thru/common/primitives/types.ts +2428 -0
  123. package/src/manager/abi/thru/program/manager/types.ts +3814 -0
  124. package/src/manager/accounts.ts +44 -0
  125. package/src/manager/constants.ts +16 -0
  126. package/src/manager/derivation.ts +32 -0
  127. package/src/manager/errors.ts +47 -0
  128. package/src/manager/index.test.ts +108 -0
  129. package/src/manager/index.ts +68 -0
  130. package/src/manager/instructions.ts +281 -0
  131. package/src/manager/types.ts +95 -0
  132. package/src/manager/validation.ts +35 -0
  133. package/src/multicall/index.test.ts +11 -2
  134. package/src/multicall/index.ts +12 -5
  135. package/src/oracle/index.ts +4 -0
  136. package/src/passkey-manager/constants.ts +2 -1
  137. package/src/passkey-manager/validate.test.ts +2 -2
  138. package/src/uploader/abi/thru/common/primitives/types.ts +2428 -0
  139. package/src/uploader/abi/thru/program/uploader/types.ts +3022 -0
  140. package/src/uploader/accounts.ts +38 -0
  141. package/src/uploader/constants.ts +14 -0
  142. package/src/uploader/derivation.ts +34 -0
  143. package/src/uploader/errors.ts +25 -0
  144. package/src/uploader/index.test.ts +107 -0
  145. package/src/uploader/index.ts +34 -0
  146. package/src/uploader/instructions.ts +163 -0
  147. package/src/uploader/types.ts +67 -0
  148. package/src/utils/helpers.ts +121 -0
  149. package/tsup.config.ts +5 -0
  150. package/dist/chunk-J7B7XYOI.js.map +0 -1
  151. package/dist/chunk-P5OABVJI.js +0 -28
  152. package/dist/chunk-P5OABVJI.js.map +0 -1
package/README.md CHANGED
@@ -2,6 +2,90 @@
2
2
 
3
3
  TypeScript bindings and helpers for Thru on-chain programs.
4
4
 
5
+ ## Managed program primitives
6
+
7
+ The deployment system programs have dedicated SDK entry points:
8
+
9
+ - `@thru/programs/manager` manages seed-derived program accounts.
10
+ - `@thru/programs/abi-manager` manages official and external ABI accounts.
11
+ - `@thru/programs/uploader` manages temporary bulk-upload accounts.
12
+
13
+ Each entry point exports canonical program IDs, address derivation, account
14
+ parsers, error decoding, generated ABI types, raw instruction builders, and
15
+ account-aware instruction callbacks. The callbacks can be passed directly as
16
+ `instructionData` when building a transaction with `@thru/sdk`.
17
+
18
+ ```typescript
19
+ import {
20
+ deriveManagedProgramAddresses,
21
+ createUpgradeProgramInstruction,
22
+ } from "@thru/programs/manager";
23
+
24
+ const addresses = deriveManagedProgramAddresses("nft");
25
+ const instructionData = createUpgradeProgramInstruction({
26
+ metaAccount: metaAddressBytes,
27
+ programAccount: programAddressBytes,
28
+ sourceBufferAccount: uploadBufferAddressBytes,
29
+ sourceSize: programBytes.length,
30
+ });
31
+ ```
32
+
33
+ These modules encode individual program calls. Multi-transaction upload,
34
+ signing, retry, atomic deployment, and verification policy belongs in the
35
+ deployment workflow rather than these low-level SDKs.
36
+
37
+ ## Managed program deployment
38
+
39
+ `@thru/programs/deploy` uploads and manages program images and official ABIs
40
+ using `@thru/sdk`. A combined program and ABI deploy or upgrade commits both
41
+ artifacts in one multicall transaction.
42
+
43
+ ```typescript
44
+ import { readFile } from "node:fs/promises";
45
+ import { deploy, type DeployProgramResult } from "@thru/programs/deploy";
46
+
47
+ const result: DeployProgramResult = await deploy.deployProgram({
48
+ seed: "nft",
49
+ signer: {
50
+ address: "ta...",
51
+ privateKey: process.env.THRU_PRIVATE_KEY!,
52
+ },
53
+ program: await readFile("./nft.bin"),
54
+ abi: await readFile("./nft.abi.yaml"),
55
+ onProgress: (event) => console.log(event.phase, event.status),
56
+ });
57
+
58
+ console.log(result.programAccountAddress, result.transactionSignature);
59
+ ```
60
+
61
+ The same namespace exposes `deployProgramABI`, `upgradeProgram`, and
62
+ `upgradeProgramABI`. Each operation is also exported directly. Create methods
63
+ fail before uploading when a final account already exists. Upgrade methods
64
+ require open accounts controlled by the signer.
65
+
66
+ `inspectProgramDeployment` provides the same canonical ownership, authority,
67
+ relationship, and optional byte checks without submitting a transaction. It
68
+ reports program and ABI account pairs as `missing`, `partial`, or `present`.
69
+
70
+ Results include the authority, derived program and ABI addresses, program
71
+ version or ABI revision, artifact sizes, the final signature, warnings, and an
72
+ `UploadArtifactResult` for each upload. Upload details include temporary
73
+ addresses, SHA-256, resume status, all submission signatures, and cleanup
74
+ status. Temporary-account cleanup is best effort; cleanup failures are returned
75
+ as warnings and do not change a successful final transaction.
76
+
77
+ Failures throw `DeployError`. Its stable `code` is one of `INVALID_INPUT`,
78
+ `SIGNER_MISMATCH`, `TARGET_EXISTS`, `TARGET_NOT_FOUND`, `TARGET_FINALIZED`,
79
+ `UPLOAD_CONFLICT`, `TRANSACTION_FAILED`, `VERIFICATION_FAILED`,
80
+ `OUTCOME_UNKNOWN`, or `RPC_ERROR`. When available, the error also includes the
81
+ phase, transaction signature, VM/user error codes, derived addresses, and
82
+ cleanup results.
83
+
84
+ Program images must use managed image version 1 and end in an eight-byte zero
85
+ trailer. ABI input must be valid, self-contained UTF-8 YAML; prepare or flatten
86
+ local path imports before publishing. The default upload chunk size is 30,720
87
+ bytes and may be set from 1,024 through 31,000 bytes.
88
+
5
89
  ## Oracle read SDK
6
90
 
7
91
  `@thru/programs/oracle` provides typed, ABI-backed helpers for applications that
@@ -23,18 +107,16 @@ pnpm add @thru/programs @thru/sdk
23
107
  import { createThruClient } from "@thru/sdk/client";
24
108
  import {
25
109
  deriveOracleFeedAddress,
110
+ ORACLE_PROGRAM_ADDRESS,
26
111
  parseOracleFeedAccount,
27
112
  } from "@thru/programs/oracle";
28
113
 
29
114
  const thru = createThruClient({
30
115
  baseUrl: "https://rpc.alphanet.thru.org",
31
116
  });
32
- const oracleProgramAddress =
33
- "taAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgI";
34
-
35
117
  const { address: feedAddress } = deriveOracleFeedAddress(
36
118
  thru,
37
- oracleProgramAddress,
119
+ ORACLE_PROGRAM_ADDRESS,
38
120
  "btc-usd:ticker@coinbase",
39
121
  );
40
122
 
@@ -95,13 +177,13 @@ Unknown error codes return `null`.
95
177
 
96
178
  ### API reference
97
179
 
98
- | Export | Description |
99
- |---|---|
100
- | `deriveOracleFeedAddress(thru, programAddress, seed)` | Derive a permanent Oracle feed address and return its normalized seed |
101
- | `normalizeOracleFeedSeed(seed)` | Convert a string or byte array to the 32-byte seed used by the program |
102
- | `parseOracleFeedAccount(account)` | Decode an SDK `Account` or raw account bytes into a typed price or boolean feed |
103
- | `parseOracleEvent(data)` | Decode raw event bytes into a typed price or boolean update event |
104
- | `oracleProgramErrorFromCode(code)` | Map a numeric user-error code to `OracleProgramError`, or return `null` |
180
+ | Export | Description |
181
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
182
+ | `deriveOracleFeedAddress(thru, programAddress, seed)` | Derive a permanent Oracle feed address and return its normalized seed |
183
+ | `normalizeOracleFeedSeed(seed)` | Convert a string or byte array to the 32-byte seed used by the program |
184
+ | `parseOracleFeedAccount(account)` | Decode an SDK `Account` or raw account bytes into a typed price or boolean feed |
185
+ | `parseOracleEvent(data)` | Decode raw event bytes into a typed price or boolean update event |
186
+ | `oracleProgramErrorFromCode(code)` | Map a numeric user-error code to `OracleProgramError`, or return `null` |
105
187
 
106
188
  String seeds are UTF-8 encoded, truncated to 32 bytes, and zero-padded when
107
189
  shorter. Feed and event parsers require the complete raw payload and reject
@@ -123,19 +205,19 @@ pnpm add @thru/programs @thru/sdk
123
205
  import {
124
206
  createInitializeMintInstruction,
125
207
  deriveMintAddress,
126
- } from '@thru/programs/token';
208
+ } from "@thru/programs/token";
127
209
 
128
210
  const { address, bytes, derivedSeed } = deriveMintAddress(
129
211
  mintAuthorityAddress,
130
212
  seedHex,
131
- tokenProgramAddress
213
+ tokenProgramAddress,
132
214
  );
133
215
 
134
216
  const instruction = createInitializeMintInstruction({
135
217
  mintAccountBytes: bytes,
136
218
  decimals: 6,
137
219
  mintAuthorityBytes: authorityBytes,
138
- ticker: 'MYTOKEN',
220
+ ticker: "MYTOKEN",
139
221
  seedHex,
140
222
  stateProof,
141
223
  });
@@ -147,12 +229,12 @@ const instruction = createInitializeMintInstruction({
147
229
  import {
148
230
  createInitializeAccountInstruction,
149
231
  deriveTokenAccountAddress,
150
- } from '@thru/programs/token';
232
+ } from "@thru/programs/token";
151
233
 
152
234
  const { bytes: tokenAccountBytes, derivedSeed } = deriveTokenAccountAddress(
153
235
  ownerAddress,
154
236
  mintAddress,
155
- tokenProgramAddress
237
+ tokenProgramAddress,
156
238
  );
157
239
 
158
240
  const instruction = createInitializeAccountInstruction({
@@ -167,7 +249,7 @@ const instruction = createInitializeAccountInstruction({
167
249
  #### Transfer tokens
168
250
 
169
251
  ```typescript
170
- import { createTransferInstruction } from '@thru/programs/token';
252
+ import { createTransferInstruction } from "@thru/programs/token";
171
253
 
172
254
  const instruction = createTransferInstruction({
173
255
  sourceAccountBytes,
@@ -179,7 +261,10 @@ const instruction = createTransferInstruction({
179
261
  #### Parse on-chain account data
180
262
 
181
263
  ```typescript
182
- import { parseMintAccountData, parseTokenAccountData } from '@thru/programs/token';
264
+ import {
265
+ parseMintAccountData,
266
+ parseTokenAccountData,
267
+ } from "@thru/programs/token";
183
268
 
184
269
  const mintInfo = parseMintAccountData(account);
185
270
  // { decimals, supply, creator, mintAuthority, freezeAuthority, ticker, ... }
@@ -191,7 +276,7 @@ const tokenInfo = parseTokenAccountData(account);
191
276
  #### Format token amounts for display
192
277
 
193
278
  ```typescript
194
- import { formatRawAmount } from '@thru/programs/token';
279
+ import { formatRawAmount } from "@thru/programs/token";
195
280
 
196
281
  formatRawAmount(1_500_000n, 6); // "1.5"
197
282
  formatRawAmount(1_000_000n, 6); // "1"
@@ -211,29 +296,29 @@ formatRawAmount(1_000_000n, 6); // "1"
211
296
 
212
297
  Each instruction builder returns an `InstructionData` function that accepts an `AccountLookupContext` and resolves to the serialized instruction bytes.
213
298
 
214
- | Function | Description |
215
- |---|---|
216
- | `createInitializeMintInstruction(args)` | Create a new token mint with ticker, decimals, and authorities |
217
- | `createInitializeAccountInstruction(args)` | Create a token account for a given owner and mint |
218
- | `createMintToInstruction(args)` | Mint new tokens to a destination account |
219
- | `createTransferInstruction(args)` | Transfer tokens between accounts |
299
+ | Function | Description |
300
+ | ---------------------------------------------- | ------------------------------------------------------------------ |
301
+ | `createInitializeMintInstruction(args)` | Create a new token mint with ticker, decimals, and authorities |
302
+ | `createInitializeAccountInstruction(args)` | Create a token account for a given owner and mint |
303
+ | `createMintToInstruction(args)` | Mint new tokens to a destination account |
304
+ | `createTransferInstruction(args)` | Transfer tokens between accounts |
220
305
  | `buildTokenInstructionBytes(variant, payload)` | Low-level helper to wrap a payload in a token instruction envelope |
221
306
 
222
307
  #### Derivation
223
308
 
224
- | Function | Description |
225
- |---|---|
226
- | `deriveMintAddress(authority, seed, programAddress)` | Derive the deterministic address for a token mint |
309
+ | Function | Description |
310
+ | --------------------------------------------------------------- | ---------------------------------------------------- |
311
+ | `deriveMintAddress(authority, seed, programAddress)` | Derive the deterministic address for a token mint |
227
312
  | `deriveTokenAccountAddress(owner, mint, programAddress, seed?)` | Derive the deterministic address for a token account |
228
- | `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
313
+ | `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
229
314
 
230
315
  #### Account Parsing
231
316
 
232
- | Function | Description |
233
- |---|---|
234
- | `parseMintAccountData(account)` | Parse raw account data into `MintAccountInfo` |
235
- | `parseTokenAccountData(account)` | Parse raw account data into `TokenAccountInfo` |
236
- | `isAccountNotFoundError(err)` | Check if an error represents a missing account (code 5) |
317
+ | Function | Description |
318
+ | -------------------------------- | ------------------------------------------------------- |
319
+ | `parseMintAccountData(account)` | Parse raw account data into `MintAccountInfo` |
320
+ | `parseTokenAccountData(account)` | Parse raw account data into `TokenAccountInfo` |
321
+ | `isAccountNotFoundError(err)` | Check if an error represents a missing account (code 5) |
237
322
 
238
323
  #### Types
239
324
 
@@ -258,11 +343,11 @@ interface TokenAccountInfo {
258
343
 
259
344
  ### Constants
260
345
 
261
- | Constant | Value | Description |
262
- |---|---|---|
263
- | `PUBKEY_LENGTH` | `32` | Length of a public key in bytes |
264
- | `TICKER_MAX_LENGTH` | `8` | Maximum ticker string length |
265
- | `ZERO_PUBKEY` | `Uint8Array(32)` | 32 zero bytes, used as a null public key |
346
+ | Constant | Value | Description |
347
+ | ------------------- | ---------------- | ---------------------------------------- |
348
+ | `PUBKEY_LENGTH` | `32` | Length of a public key in bytes |
349
+ | `TICKER_MAX_LENGTH` | `8` | Maximum ticker string length |
350
+ | `ZERO_PUBKEY` | `Uint8Array(32)` | 32 zero bytes, used as a null public key |
266
351
 
267
352
  ## Build
268
353