@thru/programs 0.3.1 → 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 +122 -17
- package/dist/clob/index.cjs +2 -0
- package/dist/clob/index.cjs.map +1 -1
- package/dist/clob/index.d.cts +2 -1
- package/dist/clob/index.d.ts +2 -1
- package/dist/clob/index.js +2 -1
- package/dist/clob/index.js.map +1 -1
- package/dist/oracle/index.cjs +6378 -0
- package/dist/oracle/index.cjs.map +1 -0
- package/dist/oracle/index.d.cts +74 -0
- package/dist/oracle/index.d.ts +74 -0
- package/dist/oracle/index.js +6366 -0
- package/dist/oracle/index.js.map +1 -0
- package/package.json +7 -2
- package/src/clob/index.ts +3 -0
- package/src/oracle/abi/thru/common/primitives/types.ts +2428 -0
- package/src/oracle/abi/thru/program/oracle/types.ts +5535 -0
- package/src/oracle/accounts.ts +65 -0
- package/src/oracle/constants.ts +7 -0
- package/src/oracle/decode.ts +32 -0
- package/src/oracle/derivation.ts +25 -0
- package/src/oracle/errors.ts +23 -0
- package/src/oracle/events.ts +81 -0
- package/src/oracle/index.test.ts +81 -0
- package/src/oracle/index.ts +22 -0
- package/src/oracle/types.ts +43 -0
- package/tsup.config.ts +8 -7
package/README.md
CHANGED
|
@@ -1,18 +1,123 @@
|
|
|
1
|
-
# @thru/programs
|
|
1
|
+
# @thru/programs
|
|
2
2
|
|
|
3
|
-
TypeScript bindings for
|
|
3
|
+
TypeScript bindings and helpers for Thru on-chain programs.
|
|
4
4
|
|
|
5
|
-
##
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
118
|
+
### Basic Usage
|
|
14
119
|
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
208
|
+
### API Reference
|
|
104
209
|
|
|
105
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
238
|
+
#### Types
|
|
134
239
|
|
|
135
240
|
```typescript
|
|
136
241
|
interface MintAccountInfo {
|
package/dist/clob/index.cjs
CHANGED
|
@@ -14361,6 +14361,7 @@ var CLOB_STATUS_FLAG_PAUSED = 1 << 0;
|
|
|
14361
14361
|
var CLOB_STATUS_FLAG_POST_ONLY = 1 << 1;
|
|
14362
14362
|
var CLOB_STATUS_FLAG_WITHDRAWALS_FROZEN = 1 << 2;
|
|
14363
14363
|
var CLOB_STATUS_FLAG_DEPOSITS_FROZEN = 1 << 3;
|
|
14364
|
+
var CLOB_PROGRAM_ADDRESS = "tamjQOFxFORIZhqbJjN83oAkRmSbKhLmULpvSHblK4GGIg";
|
|
14364
14365
|
var CLOB_ORDER_TYPE_GTC = 0;
|
|
14365
14366
|
var CLOB_ORDER_TYPE_MTL = 1;
|
|
14366
14367
|
var CLOB_ORDER_TYPE_ALO = 2;
|
|
@@ -15003,6 +15004,7 @@ exports.CLOB_ORDER_TYPE_FOK = CLOB_ORDER_TYPE_FOK;
|
|
|
15003
15004
|
exports.CLOB_ORDER_TYPE_GTC = CLOB_ORDER_TYPE_GTC;
|
|
15004
15005
|
exports.CLOB_ORDER_TYPE_IOC = CLOB_ORDER_TYPE_IOC;
|
|
15005
15006
|
exports.CLOB_ORDER_TYPE_MTL = CLOB_ORDER_TYPE_MTL;
|
|
15007
|
+
exports.CLOB_PROGRAM_ADDRESS = CLOB_PROGRAM_ADDRESS;
|
|
15006
15008
|
exports.CLOB_SEATLESS_SEAT_IDX = CLOB_SEATLESS_SEAT_IDX;
|
|
15007
15009
|
exports.CLOB_SEAT_ENTRY_SIZE = CLOB_SEAT_ENTRY_SIZE;
|
|
15008
15010
|
exports.CLOB_STATUS_FLAG_DEPOSITS_FROZEN = CLOB_STATUS_FLAG_DEPOSITS_FROZEN;
|