@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.
- package/README.md +123 -37
- package/dist/abi-manager/index.cjs +9568 -0
- package/dist/abi-manager/index.cjs.map +1 -0
- package/dist/abi-manager/index.d.cts +2169 -0
- package/dist/abi-manager/index.d.ts +2169 -0
- package/dist/abi-manager/index.js +4 -0
- package/dist/abi-manager/index.js.map +1 -0
- package/dist/amm/index.cjs +1 -3
- package/dist/amm/index.cjs.map +1 -1
- package/dist/amm/index.d.cts +1 -1
- package/dist/amm/index.d.ts +1 -1
- package/dist/amm/index.js +2 -2
- package/dist/amm/index.js.map +1 -1
- package/dist/chunk-6IC6CO5S.js +9443 -0
- package/dist/chunk-6IC6CO5S.js.map +1 -0
- package/dist/chunk-7FBCBZIY.js +41 -0
- package/dist/chunk-7FBCBZIY.js.map +1 -0
- package/dist/chunk-BNYDH4ZP.js +4351 -0
- package/dist/chunk-BNYDH4ZP.js.map +1 -0
- package/dist/chunk-OODN6LJA.js +6567 -0
- package/dist/chunk-OODN6LJA.js.map +1 -0
- package/dist/chunk-YX7BLFQZ.js +81 -0
- package/dist/chunk-YX7BLFQZ.js.map +1 -0
- package/dist/clob/index.cjs +6674 -3209
- package/dist/clob/index.cjs.map +1 -1
- package/dist/clob/index.d.cts +1114 -52
- package/dist/clob/index.d.ts +1114 -52
- package/dist/clob/index.js +6812 -3393
- package/dist/clob/index.js.map +1 -1
- package/dist/deploy/index.cjs +24734 -0
- package/dist/deploy/index.cjs.map +1 -0
- package/dist/deploy/index.d.cts +180 -0
- package/dist/deploy/index.d.ts +180 -0
- package/dist/deploy/index.js +1846 -0
- package/dist/deploy/index.js.map +1 -0
- package/dist/helpers-DD7q61nr.d.cts +7 -0
- package/dist/helpers-DD7q61nr.d.ts +7 -0
- package/dist/manager/index.cjs +6680 -0
- package/dist/manager/index.cjs.map +1 -0
- package/dist/manager/index.d.cts +1279 -0
- package/dist/manager/index.d.ts +1279 -0
- package/dist/manager/index.js +4 -0
- package/dist/manager/index.js.map +1 -0
- package/dist/passkey-manager/index.cjs +4 -5
- package/dist/passkey-manager/index.cjs.map +1 -1
- package/dist/passkey-manager/index.js +2 -2
- package/dist/uploader/index.cjs +4442 -0
- package/dist/uploader/index.cjs.map +1 -0
- package/dist/uploader/index.d.cts +761 -0
- package/dist/uploader/index.d.ts +761 -0
- package/dist/uploader/index.js +4 -0
- package/dist/uploader/index.js.map +1 -0
- package/package.json +22 -2
- package/src/abi-manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
- package/src/abi-manager/abi/thru/common/primitives/types.ts +2428 -0
- package/src/abi-manager/abi/thru/program/abi_manager/types.ts +7037 -0
- package/src/abi-manager/accounts.ts +91 -0
- package/src/abi-manager/constants.ts +19 -0
- package/src/abi-manager/derivation.ts +86 -0
- package/src/abi-manager/errors.ts +48 -0
- package/src/abi-manager/index.test.ts +136 -0
- package/src/abi-manager/index.ts +56 -0
- package/src/abi-manager/instructions.ts +573 -0
- package/src/abi-manager/types.ts +150 -0
- package/src/amm/index.test.ts +8 -2
- package/src/amm/index.ts +1 -1
- package/src/clob/abi/thru/program/clob/types.ts +6981 -3070
- package/src/clob/exchange-client.test.ts +115 -2
- package/src/clob/exchange-client.ts +52 -13
- package/src/clob/exchange.test.ts +18 -16
- package/src/clob/exchange.ts +4 -0
- package/src/clob/index.test.ts +134 -7
- package/src/clob/index.ts +302 -10
- package/src/clob/price.test.ts +32 -0
- package/src/clob/price.ts +77 -0
- package/src/deploy/accounts.ts +208 -0
- package/src/deploy/chain.ts +163 -0
- package/src/deploy/constants.ts +25 -0
- package/src/deploy/deploy.test.ts +349 -0
- package/src/deploy/errors.ts +72 -0
- package/src/deploy/index.ts +44 -0
- package/src/deploy/inspection.ts +146 -0
- package/src/deploy/seeds.ts +29 -0
- package/src/deploy/types.ts +178 -0
- package/src/deploy/uploader.test.ts +326 -0
- package/src/deploy/uploader.ts +558 -0
- package/src/deploy/validation-imports.test.ts +55 -0
- package/src/deploy/validation.ts +183 -0
- package/src/deploy/workflows.test.ts +422 -0
- package/src/deploy/workflows.ts +1088 -0
- package/src/helpers/bytes.test.ts +58 -0
- package/src/helpers/bytes.ts +28 -3
- package/src/manager/abi/thru/blockchain/state_proof/types.ts +1906 -0
- package/src/manager/abi/thru/common/primitives/types.ts +2428 -0
- package/src/manager/abi/thru/program/manager/types.ts +3814 -0
- package/src/manager/accounts.ts +44 -0
- package/src/manager/constants.ts +16 -0
- package/src/manager/derivation.ts +32 -0
- package/src/manager/errors.ts +47 -0
- package/src/manager/index.test.ts +108 -0
- package/src/manager/index.ts +68 -0
- package/src/manager/instructions.ts +281 -0
- package/src/manager/types.ts +95 -0
- package/src/manager/validation.ts +35 -0
- package/src/uploader/abi/thru/common/primitives/types.ts +2428 -0
- package/src/uploader/abi/thru/program/uploader/types.ts +3022 -0
- package/src/uploader/accounts.ts +38 -0
- package/src/uploader/constants.ts +14 -0
- package/src/uploader/derivation.ts +34 -0
- package/src/uploader/errors.ts +25 -0
- package/src/uploader/index.test.ts +107 -0
- package/src/uploader/index.ts +34 -0
- package/src/uploader/instructions.ts +163 -0
- package/src/uploader/types.ts +67 -0
- package/src/utils/helpers.ts +121 -0
- package/tsup.config.ts +4 -0
- package/dist/chunk-P5OABVJI.js +0 -28
- 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
|
|
99
|
-
|
|
100
|
-
| `deriveOracleFeedAddress(thru, programAddress, seed)` | Derive a permanent Oracle feed address and return its normalized seed
|
|
101
|
-
| `normalizeOracleFeedSeed(seed)`
|
|
102
|
-
| `parseOracleFeedAccount(account)`
|
|
103
|
-
| `parseOracleEvent(data)`
|
|
104
|
-
| `oracleProgramErrorFromCode(code)`
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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 {
|
|
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
|
|
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
|
|
215
|
-
|
|
216
|
-
| `createInitializeMintInstruction(args)`
|
|
217
|
-
| `createInitializeAccountInstruction(args)`
|
|
218
|
-
| `createMintToInstruction(args)`
|
|
219
|
-
| `createTransferInstruction(args)`
|
|
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
|
|
225
|
-
|
|
226
|
-
| `deriveMintAddress(authority, seed, programAddress)`
|
|
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?)`
|
|
314
|
+
| `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
|
|
229
315
|
|
|
230
316
|
#### Account Parsing
|
|
231
317
|
|
|
232
|
-
| Function
|
|
233
|
-
|
|
234
|
-
| `parseMintAccountData(account)`
|
|
235
|
-
| `parseTokenAccountData(account)` | Parse raw account data into `TokenAccountInfo`
|
|
236
|
-
| `isAccountNotFoundError(err)`
|
|
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
|
|
262
|
-
|
|
263
|
-
| `PUBKEY_LENGTH`
|
|
264
|
-
| `TICKER_MAX_LENGTH` | `8`
|
|
265
|
-
| `ZERO_PUBKEY`
|
|
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
|
|