@thru/programs 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,18 +1,123 @@
1
- # @thru/programs/token
1
+ # @thru/programs
2
2
 
3
- TypeScript bindings for the Thru on-chain token program. Provides instruction builders, account parsers, address derivation, and formatting utilities for creating and managing tokens on the Thru network.
3
+ TypeScript bindings and helpers for Thru on-chain programs.
4
4
 
5
- ## Installation
5
+ ## Oracle read SDK
6
+
7
+ `@thru/programs/oracle` provides typed, ABI-backed helpers for applications that
8
+ read Oracle feeds. It supports deterministic feed-address derivation, price and
9
+ boolean feed decoding, update-event decoding, and program-error mapping.
10
+
11
+ The TypeScript API is read-only. Oracle reporters and other services that submit
12
+ updates should use the Rust SDK.
13
+
14
+ ### Installation
6
15
 
7
16
  ```bash
8
- pnpm add @thru/programs/token
17
+ pnpm add @thru/programs @thru/sdk
18
+ ```
19
+
20
+ ### Derive and read a feed
21
+
22
+ ```typescript
23
+ import { createThruClient } from "@thru/sdk/client";
24
+ import {
25
+ deriveOracleFeedAddress,
26
+ parseOracleFeedAccount,
27
+ } from "@thru/programs/oracle";
28
+
29
+ const thru = createThruClient({
30
+ baseUrl: "https://rpc.alphanet.thru.org",
31
+ });
32
+ const oracleProgramAddress =
33
+ "taAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgI";
34
+
35
+ const { address: feedAddress } = deriveOracleFeedAddress(
36
+ thru,
37
+ oracleProgramAddress,
38
+ "btc-usd:ticker@coinbase",
39
+ );
40
+
41
+ const account = await thru.accounts.get(feedAddress);
42
+ const feed = parseOracleFeedAccount(account);
43
+
44
+ if (feed.kind === "price") {
45
+ console.log({
46
+ name: feed.common.feedName,
47
+ price: feed.price,
48
+ exponent: feed.exponent,
49
+ lastUpdateNs: feed.common.lastUpdateNs,
50
+ });
51
+ } else {
52
+ console.log({
53
+ name: feed.common.feedName,
54
+ value: feed.value,
55
+ lastUpdateNs: feed.common.lastUpdateNs,
56
+ });
57
+ }
9
58
  ```
10
59
 
11
- Peer dependencies: `@thru/sdk/helpers`, `@thru/sdk`.
60
+ Prices and nanosecond timestamps are returned as `bigint`. A price's decimal
61
+ value is `price * 10^exponent`; callers should retain integer arithmetic until
62
+ formatting the value for display.
63
+
64
+ ### Decode an update event
65
+
66
+ Pass the raw event payload returned by the transaction or event API:
67
+
68
+ ```typescript
69
+ import { parseOracleEvent } from "@thru/programs/oracle";
70
+
71
+ const update = parseOracleEvent(eventData);
72
+
73
+ if (update.kind === "priceUpdate") {
74
+ console.log(update.feedAddress, update.oldPrice, update.newPrice);
75
+ } else {
76
+ console.log(update.feedAddress, update.oldValue, update.newValue);
77
+ }
78
+ ```
79
+
80
+ ### Decode a program error
81
+
82
+ ```typescript
83
+ import {
84
+ OracleProgramError,
85
+ oracleProgramErrorFromCode,
86
+ } from "@thru/programs/oracle";
87
+
88
+ const error = oracleProgramErrorFromCode(userErrorCode);
89
+ if (error === OracleProgramError.UpdateTooStale) {
90
+ // Reject or retry the stale update according to the application policy.
91
+ }
92
+ ```
93
+
94
+ Unknown error codes return `null`.
95
+
96
+ ### API reference
97
+
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` |
105
+
106
+ String seeds are UTF-8 encoded, truncated to 32 bytes, and zero-padded when
107
+ shorter. Feed and event parsers require the complete raw payload and reject
108
+ unknown feed types, malformed lengths, and invalid boolean values.
109
+
110
+ ## Token SDK
111
+
112
+ ### Installation
113
+
114
+ ```bash
115
+ pnpm add @thru/programs @thru/sdk
116
+ ```
12
117
 
13
- ## Basic Usage
118
+ ### Basic Usage
14
119
 
15
- ### Create a new token mint
120
+ #### Create a new token mint
16
121
 
17
122
  ```typescript
18
123
  import {
@@ -36,7 +141,7 @@ const instruction = createInitializeMintInstruction({
36
141
  });
37
142
  ```
38
143
 
39
- ### Initialize a token account
144
+ #### Initialize a token account
40
145
 
41
146
  ```typescript
42
147
  import {
@@ -59,7 +164,7 @@ const instruction = createInitializeAccountInstruction({
59
164
  });
60
165
  ```
61
166
 
62
- ### Transfer tokens
167
+ #### Transfer tokens
63
168
 
64
169
  ```typescript
65
170
  import { createTransferInstruction } from '@thru/programs/token';
@@ -71,7 +176,7 @@ const instruction = createTransferInstruction({
71
176
  });
72
177
  ```
73
178
 
74
- ### Parse on-chain account data
179
+ #### Parse on-chain account data
75
180
 
76
181
  ```typescript
77
182
  import { parseMintAccountData, parseTokenAccountData } from '@thru/programs/token';
@@ -83,7 +188,7 @@ const tokenInfo = parseTokenAccountData(account);
83
188
  // { mint, owner, amount, isFrozen }
84
189
  ```
85
190
 
86
- ### Format token amounts for display
191
+ #### Format token amounts for display
87
192
 
88
193
  ```typescript
89
194
  import { formatRawAmount } from '@thru/programs/token';
@@ -92,7 +197,7 @@ formatRawAmount(1_500_000n, 6); // "1.5"
92
197
  formatRawAmount(1_000_000n, 6); // "1"
93
198
  ```
94
199
 
95
- ## Key Capabilities
200
+ ### Key Capabilities
96
201
 
97
202
  - **Instruction builders** -- `createInitializeMintInstruction`, `createInitializeAccountInstruction`, `createMintToInstruction`, `createTransferInstruction`
98
203
  - **Address derivation** -- `deriveMintAddress`, `deriveTokenAccountAddress`, `deriveWalletSeed`
@@ -100,9 +205,9 @@ formatRawAmount(1_000_000n, 6); // "1"
100
205
  - **Formatting utilities** -- `formatRawAmount`, `bytesToHex`, `hexToBytes`
101
206
  - **ABI codegen** -- instruction payloads are built using auto-generated builders from the token program ABI
102
207
 
103
- ## API Reference
208
+ ### API Reference
104
209
 
105
- ### Instructions
210
+ #### Instructions
106
211
 
107
212
  Each instruction builder returns an `InstructionData` function that accepts an `AccountLookupContext` and resolves to the serialized instruction bytes.
108
213
 
@@ -114,7 +219,7 @@ Each instruction builder returns an `InstructionData` function that accepts an `
114
219
  | `createTransferInstruction(args)` | Transfer tokens between accounts |
115
220
  | `buildTokenInstructionBytes(variant, payload)` | Low-level helper to wrap a payload in a token instruction envelope |
116
221
 
117
- ### Derivation
222
+ #### Derivation
118
223
 
119
224
  | Function | Description |
120
225
  |---|---|
@@ -122,7 +227,7 @@ Each instruction builder returns an `InstructionData` function that accepts an `
122
227
  | `deriveTokenAccountAddress(owner, mint, programAddress, seed?)` | Derive the deterministic address for a token account |
123
228
  | `deriveWalletSeed(walletAddress, extraSeeds?)` | Derive a seed from a wallet address |
124
229
 
125
- ### Account Parsing
230
+ #### Account Parsing
126
231
 
127
232
  | Function | Description |
128
233
  |---|---|
@@ -130,7 +235,7 @@ Each instruction builder returns an `InstructionData` function that accepts an `
130
235
  | `parseTokenAccountData(account)` | Parse raw account data into `TokenAccountInfo` |
131
236
  | `isAccountNotFoundError(err)` | Check if an error represents a missing account (code 5) |
132
237
 
133
- ### Types
238
+ #### Types
134
239
 
135
240
  ```typescript
136
241
  interface MintAccountInfo {