@thru/programs 0.3.4 → 0.3.5

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 (118) hide show
  1. package/README.md +123 -37
  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 +1 -3
  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 +2 -2
  13. package/dist/amm/index.js.map +1 -1
  14. package/dist/chunk-6IC6CO5S.js +9443 -0
  15. package/dist/chunk-6IC6CO5S.js.map +1 -0
  16. package/dist/chunk-7FBCBZIY.js +41 -0
  17. package/dist/chunk-7FBCBZIY.js.map +1 -0
  18. package/dist/chunk-BNYDH4ZP.js +4351 -0
  19. package/dist/chunk-BNYDH4ZP.js.map +1 -0
  20. package/dist/chunk-OODN6LJA.js +6567 -0
  21. package/dist/chunk-OODN6LJA.js.map +1 -0
  22. package/dist/chunk-YX7BLFQZ.js +81 -0
  23. package/dist/chunk-YX7BLFQZ.js.map +1 -0
  24. package/dist/clob/index.cjs +6674 -3209
  25. package/dist/clob/index.cjs.map +1 -1
  26. package/dist/clob/index.d.cts +1114 -52
  27. package/dist/clob/index.d.ts +1114 -52
  28. package/dist/clob/index.js +6812 -3393
  29. package/dist/clob/index.js.map +1 -1
  30. package/dist/deploy/index.cjs +24734 -0
  31. package/dist/deploy/index.cjs.map +1 -0
  32. package/dist/deploy/index.d.cts +180 -0
  33. package/dist/deploy/index.d.ts +180 -0
  34. package/dist/deploy/index.js +1846 -0
  35. package/dist/deploy/index.js.map +1 -0
  36. package/dist/helpers-DD7q61nr.d.cts +7 -0
  37. package/dist/helpers-DD7q61nr.d.ts +7 -0
  38. package/dist/manager/index.cjs +6680 -0
  39. package/dist/manager/index.cjs.map +1 -0
  40. package/dist/manager/index.d.cts +1279 -0
  41. package/dist/manager/index.d.ts +1279 -0
  42. package/dist/manager/index.js +4 -0
  43. package/dist/manager/index.js.map +1 -0
  44. package/dist/passkey-manager/index.cjs +4 -5
  45. package/dist/passkey-manager/index.cjs.map +1 -1
  46. package/dist/passkey-manager/index.js +2 -2
  47. package/dist/uploader/index.cjs +4442 -0
  48. package/dist/uploader/index.cjs.map +1 -0
  49. package/dist/uploader/index.d.cts +761 -0
  50. package/dist/uploader/index.d.ts +761 -0
  51. package/dist/uploader/index.js +4 -0
  52. package/dist/uploader/index.js.map +1 -0
  53. package/package.json +22 -2
  54. package/src/abi-manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
  55. package/src/abi-manager/abi/thru/common/primitives/types.ts +2428 -0
  56. package/src/abi-manager/abi/thru/program/abi_manager/types.ts +7037 -0
  57. package/src/abi-manager/accounts.ts +91 -0
  58. package/src/abi-manager/constants.ts +19 -0
  59. package/src/abi-manager/derivation.ts +86 -0
  60. package/src/abi-manager/errors.ts +48 -0
  61. package/src/abi-manager/index.test.ts +136 -0
  62. package/src/abi-manager/index.ts +56 -0
  63. package/src/abi-manager/instructions.ts +573 -0
  64. package/src/abi-manager/types.ts +150 -0
  65. package/src/amm/index.test.ts +8 -2
  66. package/src/amm/index.ts +1 -1
  67. package/src/clob/abi/thru/program/clob/types.ts +6981 -3070
  68. package/src/clob/exchange-client.test.ts +115 -2
  69. package/src/clob/exchange-client.ts +52 -13
  70. package/src/clob/exchange.test.ts +18 -16
  71. package/src/clob/exchange.ts +4 -0
  72. package/src/clob/index.test.ts +134 -7
  73. package/src/clob/index.ts +302 -10
  74. package/src/clob/price.test.ts +32 -0
  75. package/src/clob/price.ts +77 -0
  76. package/src/deploy/accounts.ts +208 -0
  77. package/src/deploy/chain.ts +163 -0
  78. package/src/deploy/constants.ts +25 -0
  79. package/src/deploy/deploy.test.ts +349 -0
  80. package/src/deploy/errors.ts +72 -0
  81. package/src/deploy/index.ts +44 -0
  82. package/src/deploy/inspection.ts +146 -0
  83. package/src/deploy/seeds.ts +29 -0
  84. package/src/deploy/types.ts +178 -0
  85. package/src/deploy/uploader.test.ts +326 -0
  86. package/src/deploy/uploader.ts +558 -0
  87. package/src/deploy/validation-imports.test.ts +55 -0
  88. package/src/deploy/validation.ts +183 -0
  89. package/src/deploy/workflows.test.ts +422 -0
  90. package/src/deploy/workflows.ts +1088 -0
  91. package/src/helpers/bytes.test.ts +58 -0
  92. package/src/helpers/bytes.ts +28 -3
  93. package/src/manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
  94. package/src/manager/abi/thru/common/primitives/types.ts +2428 -0
  95. package/src/manager/abi/thru/program/manager/types.ts +3814 -0
  96. package/src/manager/accounts.ts +44 -0
  97. package/src/manager/constants.ts +16 -0
  98. package/src/manager/derivation.ts +32 -0
  99. package/src/manager/errors.ts +47 -0
  100. package/src/manager/index.test.ts +108 -0
  101. package/src/manager/index.ts +68 -0
  102. package/src/manager/instructions.ts +281 -0
  103. package/src/manager/types.ts +95 -0
  104. package/src/manager/validation.ts +35 -0
  105. package/src/uploader/abi/thru/common/primitives/types.ts +2428 -0
  106. package/src/uploader/abi/thru/program/uploader/types.ts +3022 -0
  107. package/src/uploader/accounts.ts +38 -0
  108. package/src/uploader/constants.ts +14 -0
  109. package/src/uploader/derivation.ts +34 -0
  110. package/src/uploader/errors.ts +25 -0
  111. package/src/uploader/index.test.ts +107 -0
  112. package/src/uploader/index.ts +34 -0
  113. package/src/uploader/instructions.ts +163 -0
  114. package/src/uploader/types.ts +67 -0
  115. package/src/utils/helpers.ts +121 -0
  116. package/tsup.config.ts +4 -0
  117. package/dist/chunk-P5OABVJI.js +0 -28
  118. 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
@@ -29,8 +113,7 @@ import {
29
113
  const thru = createThruClient({
30
114
  baseUrl: "https://rpc.alphanet.thru.org",
31
115
  });
32
- const oracleProgramAddress =
33
- "taAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgI";
116
+ const oracleProgramAddress = "taAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgI";
34
117
 
35
118
  const { address: feedAddress } = deriveOracleFeedAddress(
36
119
  thru,
@@ -95,13 +178,13 @@ Unknown error codes return `null`.
95
178
 
96
179
  ### API reference
97
180
 
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` |
181
+ | Export | Description |
182
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
183
+ | `deriveOracleFeedAddress(thru, programAddress, seed)` | Derive a permanent Oracle feed address and return its normalized seed |
184
+ | `normalizeOracleFeedSeed(seed)` | Convert a string or byte array to the 32-byte seed used by the program |
185
+ | `parseOracleFeedAccount(account)` | Decode an SDK `Account` or raw account bytes into a typed price or boolean feed |
186
+ | `parseOracleEvent(data)` | Decode raw event bytes into a typed price or boolean update event |
187
+ | `oracleProgramErrorFromCode(code)` | Map a numeric user-error code to `OracleProgramError`, or return `null` |
105
188
 
106
189
  String seeds are UTF-8 encoded, truncated to 32 bytes, and zero-padded when
107
190
  shorter. Feed and event parsers require the complete raw payload and reject
@@ -123,19 +206,19 @@ pnpm add @thru/programs @thru/sdk
123
206
  import {
124
207
  createInitializeMintInstruction,
125
208
  deriveMintAddress,
126
- } from '@thru/programs/token';
209
+ } from "@thru/programs/token";
127
210
 
128
211
  const { address, bytes, derivedSeed } = deriveMintAddress(
129
212
  mintAuthorityAddress,
130
213
  seedHex,
131
- tokenProgramAddress
214
+ tokenProgramAddress,
132
215
  );
133
216
 
134
217
  const instruction = createInitializeMintInstruction({
135
218
  mintAccountBytes: bytes,
136
219
  decimals: 6,
137
220
  mintAuthorityBytes: authorityBytes,
138
- ticker: 'MYTOKEN',
221
+ ticker: "MYTOKEN",
139
222
  seedHex,
140
223
  stateProof,
141
224
  });
@@ -147,12 +230,12 @@ const instruction = createInitializeMintInstruction({
147
230
  import {
148
231
  createInitializeAccountInstruction,
149
232
  deriveTokenAccountAddress,
150
- } from '@thru/programs/token';
233
+ } from "@thru/programs/token";
151
234
 
152
235
  const { bytes: tokenAccountBytes, derivedSeed } = deriveTokenAccountAddress(
153
236
  ownerAddress,
154
237
  mintAddress,
155
- tokenProgramAddress
238
+ tokenProgramAddress,
156
239
  );
157
240
 
158
241
  const instruction = createInitializeAccountInstruction({
@@ -167,7 +250,7 @@ const instruction = createInitializeAccountInstruction({
167
250
  #### Transfer tokens
168
251
 
169
252
  ```typescript
170
- import { createTransferInstruction } from '@thru/programs/token';
253
+ import { createTransferInstruction } from "@thru/programs/token";
171
254
 
172
255
  const instruction = createTransferInstruction({
173
256
  sourceAccountBytes,
@@ -179,7 +262,10 @@ const instruction = createTransferInstruction({
179
262
  #### Parse on-chain account data
180
263
 
181
264
  ```typescript
182
- import { parseMintAccountData, parseTokenAccountData } from '@thru/programs/token';
265
+ import {
266
+ parseMintAccountData,
267
+ parseTokenAccountData,
268
+ } from "@thru/programs/token";
183
269
 
184
270
  const mintInfo = parseMintAccountData(account);
185
271
  // { decimals, supply, creator, mintAuthority, freezeAuthority, ticker, ... }
@@ -191,7 +277,7 @@ const tokenInfo = parseTokenAccountData(account);
191
277
  #### Format token amounts for display
192
278
 
193
279
  ```typescript
194
- import { formatRawAmount } from '@thru/programs/token';
280
+ import { formatRawAmount } from "@thru/programs/token";
195
281
 
196
282
  formatRawAmount(1_500_000n, 6); // "1.5"
197
283
  formatRawAmount(1_000_000n, 6); // "1"
@@ -211,29 +297,29 @@ formatRawAmount(1_000_000n, 6); // "1"
211
297
 
212
298
  Each instruction builder returns an `InstructionData` function that accepts an `AccountLookupContext` and resolves to the serialized instruction bytes.
213
299
 
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 |
300
+ | Function | Description |
301
+ | ---------------------------------------------- | ------------------------------------------------------------------ |
302
+ | `createInitializeMintInstruction(args)` | Create a new token mint with ticker, decimals, and authorities |
303
+ | `createInitializeAccountInstruction(args)` | Create a token account for a given owner and mint |
304
+ | `createMintToInstruction(args)` | Mint new tokens to a destination account |
305
+ | `createTransferInstruction(args)` | Transfer tokens between accounts |
220
306
  | `buildTokenInstructionBytes(variant, payload)` | Low-level helper to wrap a payload in a token instruction envelope |
221
307
 
222
308
  #### Derivation
223
309
 
224
- | Function | Description |
225
- |---|---|
226
- | `deriveMintAddress(authority, seed, programAddress)` | Derive the deterministic address for a token mint |
310
+ | Function | Description |
311
+ | --------------------------------------------------------------- | ---------------------------------------------------- |
312
+ | `deriveMintAddress(authority, seed, programAddress)` | Derive the deterministic address for a token mint |
227
313
  | `deriveTokenAccountAddress(owner, mint, programAddress, seed?)` | Derive the deterministic address for a token account |
228
- | `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
314
+ | `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
229
315
 
230
316
  #### Account Parsing
231
317
 
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) |
318
+ | Function | Description |
319
+ | -------------------------------- | ------------------------------------------------------- |
320
+ | `parseMintAccountData(account)` | Parse raw account data into `MintAccountInfo` |
321
+ | `parseTokenAccountData(account)` | Parse raw account data into `TokenAccountInfo` |
322
+ | `isAccountNotFoundError(err)` | Check if an error represents a missing account (code 5) |
237
323
 
238
324
  #### Types
239
325
 
@@ -258,11 +344,11 @@ interface TokenAccountInfo {
258
344
 
259
345
  ### Constants
260
346
 
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 |
347
+ | Constant | Value | Description |
348
+ | ------------------- | ---------------- | ---------------------------------------- |
349
+ | `PUBKEY_LENGTH` | `32` | Length of a public key in bytes |
350
+ | `TICKER_MAX_LENGTH` | `8` | Maximum ticker string length |
351
+ | `ZERO_PUBKEY` | `Uint8Array(32)` | 32 zero bytes, used as a null public key |
266
352
 
267
353
  ## Build
268
354