@thru/programs 0.4.1 → 0.4.2

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 (58) hide show
  1. package/dist/abi-manager/index.cjs +39 -2
  2. package/dist/abi-manager/index.cjs.map +1 -1
  3. package/dist/abi-manager/index.js +2 -2
  4. package/dist/amm/index.cjs +39 -2
  5. package/dist/amm/index.cjs.map +1 -1
  6. package/dist/amm/index.js +1 -1
  7. package/dist/bootstrap-addresses/index.cjs +41 -2
  8. package/dist/bootstrap-addresses/index.cjs.map +1 -1
  9. package/dist/bootstrap-addresses/index.d.cts +8 -1
  10. package/dist/bootstrap-addresses/index.d.ts +8 -1
  11. package/dist/bootstrap-addresses/index.js +1 -1
  12. package/dist/{chunk-TRPUGPZJ.js → chunk-2FFCNXCE.js} +58 -5
  13. package/dist/chunk-2FFCNXCE.js.map +1 -0
  14. package/dist/{chunk-QCJFKBAS.js → chunk-I3DLOUB4.js} +3 -3
  15. package/dist/{chunk-QCJFKBAS.js.map → chunk-I3DLOUB4.js.map} +1 -1
  16. package/dist/clob/index.cjs +41 -2
  17. package/dist/clob/index.cjs.map +1 -1
  18. package/dist/clob/index.d.cts +7 -1
  19. package/dist/clob/index.d.ts +7 -1
  20. package/dist/clob/index.js +3 -2
  21. package/dist/clob/index.js.map +1 -1
  22. package/dist/deploy/index.cjs +39 -2
  23. package/dist/deploy/index.cjs.map +1 -1
  24. package/dist/deploy/index.js +3 -3
  25. package/dist/oracle/index.cjs +39 -2
  26. package/dist/oracle/index.cjs.map +1 -1
  27. package/dist/oracle/index.js +1 -1
  28. package/dist/passkey-manager/index.cjs +42 -5
  29. package/dist/passkey-manager/index.cjs.map +1 -1
  30. package/dist/passkey-manager/index.js +1 -1
  31. package/dist/perp/index.cjs +1785 -162
  32. package/dist/perp/index.cjs.map +1 -1
  33. package/dist/perp/index.d.cts +558 -13
  34. package/dist/perp/index.d.ts +558 -13
  35. package/dist/perp/index.js +1749 -163
  36. package/dist/perp/index.js.map +1 -1
  37. package/dist/ratelimit/index.cjs +4757 -0
  38. package/dist/ratelimit/index.cjs.map +1 -0
  39. package/dist/ratelimit/index.d.cts +171 -0
  40. package/dist/ratelimit/index.d.ts +171 -0
  41. package/dist/ratelimit/index.js +4527 -0
  42. package/dist/ratelimit/index.js.map +1 -0
  43. package/package.json +7 -2
  44. package/src/bootstrap-addresses/index.test.ts +17 -0
  45. package/src/bootstrap-addresses/index.ts +12 -0
  46. package/src/clob/index.ts +7 -0
  47. package/src/perp/abi/thru/program/perp/types.ts +1949 -149
  48. package/src/perp/index.test.ts +189 -3
  49. package/src/perp/index.ts +316 -3
  50. package/src/ratelimit/abi/thru/program/ratelimit/types.ts +5448 -0
  51. package/src/ratelimit/accounts.ts +105 -0
  52. package/src/ratelimit/constants.ts +49 -0
  53. package/src/ratelimit/derivation.ts +93 -0
  54. package/src/ratelimit/index.test.ts +185 -0
  55. package/src/ratelimit/index.ts +30 -0
  56. package/src/ratelimit/instructions.ts +244 -0
  57. package/tsup.config.ts +1 -0
  58. package/dist/chunk-TRPUGPZJ.js.map +0 -1
@@ -21,12 +21,27 @@ import {
21
21
  PERP_SEAT_ARENA_ENTRIES_OFFSET,
22
22
  PERP_SEAT_ENTRY_SIZE,
23
23
  PERP_SEAT_MANAGER_RESERVED_SIZE,
24
+ createPerpFundingUpdateInstruction,
24
25
  createPerpLiquidateInstruction,
26
+ createPerpMarketSetFundingInstruction,
27
+ createPerpSettleFundingInstruction,
25
28
  createPerpMarketCreateInstruction,
26
29
  createPerpMarketRecordInstruction,
27
30
  createPerpMarketSetOracleInstruction,
28
31
  derivePerpMarketAccounts,
29
32
  parsePerpEvent,
33
+ perpFundingHourlyRate,
34
+ perpFundingParamsProblem,
35
+ perpFundingPremiumSample,
36
+ perpFundingRoundDue,
37
+ perpFundingSampleDue,
38
+ perpNextFundingRoundNs,
39
+ perpSettleFunding,
40
+ PERP_EVENT_FUNDING_ROUND,
41
+ PERP_INSTRUCTION_FUNDING_UPDATE,
42
+ PERP_INSTRUCTION_MARKET_SET_FUNDING,
43
+ PERP_INSTRUCTION_SETTLE_FUNDING,
44
+ type PerpFunding,
30
45
  parsePerpMarketAccount,
31
46
  parsePerpOrderArenaAccount,
32
47
  parsePerpSeatArenaAccount,
@@ -114,6 +129,20 @@ function marketBytes(): Uint8Array {
114
129
  view.setUint32(280, 100, true); /* liquidation_fee_bps */
115
130
  view.setInt32(284, -8, true); /* oracle_exponent */
116
131
  view.setBigUint64(288, 60_000_000_000n, true); /* max_mark_age_ns */
132
+ /* funding */
133
+ view.setBigInt64(320, -5_000_000n, true); /* funding_index (lo): -5,000,000 as signed 128 bit */
134
+ view.setBigInt64(328, -1n, true); /* funding_index (hi) */
135
+ view.setBigInt64(336, 7n, true); /* funding_balance */
136
+ view.setBigUint64(344, 3_600_000_000_000n, true); /* funding_last_round_ns */
137
+ view.setBigUint64(352, 3_660_000_000_000n, true); /* funding_last_sample_ns */
138
+ view.setBigInt64(360, -120_000n, true); /* funding_premium_sum */
139
+ view.setBigUint64(368, 19_400n, true); /* funding_impact_notional */
140
+ view.setBigInt64(376, -312n, true); /* funding_rate */
141
+ view.setUint32(384, 100, true); /* funding_interest_rate */
142
+ view.setUint32(388, 500, true); /* funding_clamp_small */
143
+ view.setUint32(392, 40_000, true); /* funding_clamp_big */
144
+ view.setUint32(396, 100, true); /* funding_premium_multiplier */
145
+ view.setUint32(400, 3, true); /* funding_sample_cnt */
117
146
  return data;
118
147
  }
119
148
 
@@ -129,6 +158,8 @@ function seatBytes(seat: {
129
158
  entryNotional: bigint;
130
159
  openBidNotional: bigint;
131
160
  openAskNotional: bigint;
161
+ fundingSnapshot?: bigint;
162
+ fundingCarry?: number;
132
163
  active: boolean;
133
164
  }): Uint8Array {
134
165
  const data = new Uint8Array(PERP_SEAT_ENTRY_SIZE);
@@ -143,6 +174,9 @@ function seatBytes(seat: {
143
174
  view.setBigUint64(80, seat.entryNotional, true);
144
175
  view.setBigUint64(88, seat.openBidNotional, true);
145
176
  view.setBigUint64(96, seat.openAskNotional, true);
177
+ view.setUint32(76, seat.fundingCarry ?? 0, true); /* funding_carry */
178
+ view.setBigInt64(104, BigInt.asIntN(64, seat.fundingSnapshot ?? 0n), true); /* funding_snapshot (lo) */
179
+ view.setBigInt64(112, (seat.fundingSnapshot ?? 0n) < 0n ? -1n : 0n, true); /* funding_snapshot (hi) */
146
180
  view.setBigUint64(120, seat.active ? 1n : 0n, true); /* non_nullable_reserved */
147
181
  return data;
148
182
  }
@@ -248,7 +282,7 @@ const minLots = (a: bigint, b: bigint) => (a < b ? a : b);
248
282
  /* Tests *********************************************************************/
249
283
 
250
284
  describe('perp account parsers', () => {
251
- it('parses the 320 byte market account', () => {
285
+ it('parses the 448 byte market account with its funding state', () => {
252
286
  const market = parsePerpMarketAccount(marketBytes());
253
287
  expect(market).toEqual<PerpMarket>({
254
288
  magic: PERP_MARKET_MAGIC,
@@ -274,12 +308,26 @@ describe('perp account parsers', () => {
274
308
  liquidationFeeBps: 100,
275
309
  oracleExponent: -8,
276
310
  maxMarkAgeNs: 60_000_000_000n,
311
+ funding: {
312
+ index: -5_000_000n,
313
+ balance: 7n,
314
+ lastRoundNs: 3_600_000_000_000n,
315
+ lastSampleNs: 3_660_000_000_000n,
316
+ premiumSum: -120_000n,
317
+ sampleCount: 3,
318
+ rate: -312n,
319
+ interestRate: 100,
320
+ clampSmall: 500,
321
+ clampBig: 40_000,
322
+ premiumMultiplier: 100,
323
+ impactNotional: 19_400n,
324
+ },
277
325
  });
278
326
  });
279
327
 
280
328
  it('rejects a short (224 byte) market', () => {
281
- expect(() => parsePerpMarketAccount(marketBytes().subarray(0, 224))).toThrow(/320 bytes/);
282
- expect(() => parsePerpMarketAccount(new Uint8Array(320))).toThrow(/not a perp market/);
329
+ expect(() => parsePerpMarketAccount(marketBytes().subarray(0, 224))).toThrow(/448 bytes/);
330
+ expect(() => parsePerpMarketAccount(new Uint8Array(448))).toThrow(/not a perp market/);
283
331
  });
284
332
 
285
333
  it('rejects a header whose margin fields are not a margined market', () => {
@@ -325,6 +373,8 @@ describe('perp account parsers', () => {
325
373
  entryNotional: 850_000_000n,
326
374
  openBidNotional: 168_000_000n,
327
375
  openAskNotional: 258_000_000n,
376
+ fundingSnapshot: -4_000_000n,
377
+ fundingCarry: 123,
328
378
  active: true,
329
379
  }),
330
380
  seatBytes({
@@ -364,6 +414,8 @@ describe('perp account parsers', () => {
364
414
  entryNotional: 850_000_000n,
365
415
  openBidNotional: 168_000_000n,
366
416
  openAskNotional: 258_000_000n,
417
+ fundingSnapshot: -4_000_000n,
418
+ fundingCarry: 123,
367
419
  },
368
420
  ]);
369
421
  });
@@ -820,3 +872,137 @@ describe('perp events', () => {
820
872
  expect(short.variant === 'liquidation' && short.targetSide).toBe('short');
821
873
  });
822
874
  });
875
+
876
+ describe('perp funding', () => {
877
+ /* The vectors match thru-perps/tests/test_txn_perp_program/test_funding.c. */
878
+ const params = { interestRate: 100, clampSmall: 500, clampBig: 40_000, premiumMultiplier: 100 };
879
+
880
+ it('turns the premium samples into the hourly rate as Lighter does', () => {
881
+ expect(perpFundingHourlyRate(0n, params)).toBe(12n);
882
+ expect(perpFundingHourlyRate(60n * 2_000n, params)).toBe(187n);
883
+ expect(perpFundingHourlyRate(-60n * 3_000n, params)).toBe(-312n);
884
+ expect(perpFundingHourlyRate(60n * 400n, params)).toBe(12n);
885
+ expect(perpFundingHourlyRate(60n * 100_000n, params)).toBe(5_000n);
886
+ expect(perpFundingHourlyRate(-60n * 100_000n, params)).toBe(-5_000n);
887
+ expect(perpFundingHourlyRate(30n * 2_000n, params)).toBe(62n);
888
+ expect(perpFundingHourlyRate(60n * 2_000n, { ...params, premiumMultiplier: 50 })).toBe((1_000n - 250n) / 8n);
889
+ expect(perpFundingHourlyRate(59n, { interestRate: 0, clampSmall: 0, clampBig: 40_000, premiumMultiplier: 100 })).toBe(0n);
890
+ expect(perpFundingHourlyRate(-59n, { interestRate: 0, clampSmall: 0, clampBig: 40_000, premiumMultiplier: 100 })).toBe(0n);
891
+ });
892
+
893
+ it('samples the premium from the impact prices', () => {
894
+ expect(perpFundingPremiumSample(200n, 220n, 240n)).toBe(100_000n);
895
+ expect(perpFundingPremiumSample(200n, 160n, 180n)).toBe(-100_000n);
896
+ expect(perpFundingPremiumSample(200n, 190n, 210n)).toBe(0n);
897
+ expect(perpFundingPremiumSample(200n, 0n, 0n)).toBe(0n);
898
+ expect(perpFundingPremiumSample(200n, 1_000n, 0n)).toBe(1_000_000n);
899
+ expect(perpFundingPremiumSample(3n, 4n, 0n)).toBe(333_333n);
900
+ expect(perpFundingPremiumSample(0n, 4n, 5n)).toBe(0n);
901
+ });
902
+
903
+ it('validates parameters like market_set_funding', () => {
904
+ const margins = { initialMarginBps: 1000, maintenanceMarginBps: 500 };
905
+ const ok = { interestRate: 100, clampSmall: 500, clampBig: 400_000, premiumMultiplier: 100, impactNotional: 1n };
906
+ expect(perpFundingParamsProblem(margins, ok)).toBeNull();
907
+ expect(perpFundingParamsProblem(margins, { ...ok, clampBig: 400_008 })).toMatch(/margin gap/);
908
+ expect(perpFundingParamsProblem(margins, { ...ok, premiumMultiplier: 101 })).toMatch(/premiumMultiplier/);
909
+ expect(perpFundingParamsProblem(margins, { ...ok, impactNotional: 0n })).toMatch(/impactNotional/);
910
+ expect(perpFundingParamsProblem(margins, { ...ok, interestRate: 1_000_001 })).toMatch(/interestRate/);
911
+ expect(perpFundingParamsProblem(margins, { ...ok, premiumMultiplier: 0, impactNotional: 0n })).toBeNull();
912
+ });
913
+
914
+ it('schedules rounds on UTC hours and samples on UTC minutes', () => {
915
+ const t0 = 1_767_225_600_000_000_000n; /* an exact UTC hour */
916
+ const funding = { lastRoundNs: t0 + 30_000_000_000n, lastSampleNs: t0 + 30_000_000_000n };
917
+ expect(perpNextFundingRoundNs(funding)).toBe(t0 + 3_600_000_000_000n);
918
+ expect(perpFundingRoundDue(funding, t0 + 3_599_999_999_999n)).toBe(false);
919
+ expect(perpFundingRoundDue(funding, t0 + 3_600_000_000_000n)).toBe(true);
920
+ expect(perpFundingSampleDue(funding, t0 + 59_000_000_000n)).toBe(false);
921
+ expect(perpFundingSampleDue(funding, t0 + 60_000_000_000n)).toBe(true);
922
+ });
923
+
924
+ it('settles seats exactly, rounding against the seat, carrying the remainder', () => {
925
+ const funding: PerpFunding = {
926
+ index: 232_800n, balance: 0n, lastRoundNs: 0n, lastSampleNs: 0n, premiumSum: 0n, sampleCount: 0, rate: 12n,
927
+ interestRate: 100, clampSmall: 500, clampBig: 40_000, premiumMultiplier: 100, impactNotional: 1n,
928
+ };
929
+ const market = { funding };
930
+ const longer = seat({ quantityQuote: 1_000n, longLots: 10n, shortLots: 0n });
931
+ const shorter = seat({ quantityQuote: 1_000n, longLots: 0n, shortLots: 10n });
932
+ const a = perpSettleFunding(market, longer);
933
+ expect(a.paid).toBe(-3n);
934
+ expect(a.seat.quantityQuote).toBe(997n);
935
+ expect(a.seat.fundingCarry).toBe(672_000);
936
+ expect(a.seat.fundingSnapshot).toBe(232_800n);
937
+ const b = perpSettleFunding(market, shorter);
938
+ expect(b.paid).toBe(2n);
939
+ expect(b.seat.quantityQuote).toBe(1_002n);
940
+ expect(b.seat.fundingCarry).toBe(328_000);
941
+ /* the collected atom is exactly the two carries */
942
+ expect((-a.paid - b.paid) * 1_000_000n).toBe(BigInt(a.seat.fundingCarry + b.seat.fundingCarry));
943
+ /* settling a settled seat is a no-op */
944
+ expect(perpSettleFunding(market, a.seat)).toEqual({ seat: a.seat, paid: 0n, badDebt: 0n });
945
+ /* a charge beyond the collateral raises a long's cost basis */
946
+ const poor = perpSettleFunding(market, seat({ quantityQuote: 1n, longLots: 10n, shortLots: 0n, entryNotional: 100n }));
947
+ expect(poor.seat.quantityQuote).toBe(0n);
948
+ expect(poor.seat.entryNotional).toBe(102n);
949
+ expect(poor.badDebt).toBe(0n);
950
+ /* a short's entry absorbs what it can; the rest is bad debt */
951
+ const down = { funding: { ...funding, index: -232_800n } };
952
+ const thin = perpSettleFunding(down, seat({ quantityQuote: 1n, longLots: 0n, shortLots: 10n, entryNotional: 1n }));
953
+ expect(thin.seat.quantityQuote).toBe(0n);
954
+ expect(thin.seat.entryNotional).toBe(0n);
955
+ expect(thin.badDebt).toBe(1n);
956
+ /* no funding on the market: nothing moves */
957
+ expect(perpSettleFunding({}, longer)).toEqual({ seat: { ...longer, fundingSnapshot: 0n, fundingCarry: 0 }, paid: 0n, badDebt: 0n });
958
+ });
959
+
960
+ it('funding update is 8 bytes; market set funding is 32', async () => {
961
+ const ctx = { getAccountIndex: () => 0 } as never;
962
+ expect([...(await createPerpFundingUpdateInstruction({ marketRecordIndex: 1 })(ctx))]).toEqual([PERP_INSTRUCTION_FUNDING_UPDATE, 1, 0, 0, 0, 0, 0, 0]);
963
+ const bytes = await createPerpMarketSetFundingInstruction({
964
+ marketRecordIndex: 1, interestRate: 100, clampSmall: 500, clampBig: 40_000, premiumMultiplier: 100, impactNotional: 19_400n,
965
+ })(ctx);
966
+ expect(bytes.length).toBe(32);
967
+ const view = new DataView(bytes.buffer, bytes.byteOffset);
968
+ expect(bytes[0]).toBe(PERP_INSTRUCTION_MARKET_SET_FUNDING);
969
+ expect(bytes[1]).toBe(1);
970
+ expect(view.getUint32(4, true)).toBe(100);
971
+ expect(view.getUint32(8, true)).toBe(500);
972
+ expect(view.getUint32(12, true)).toBe(40_000);
973
+ expect(view.getUint32(16, true)).toBe(100);
974
+ expect(view.getBigUint64(24, true)).toBe(19_400n);
975
+ expect([...(await createPerpSettleFundingInstruction({ marketRecordIndex: 1, targetSeatIndex: 42 })(ctx))]).toEqual([
976
+ PERP_INSTRUCTION_SETTLE_FUNDING, 1, 0, 0, 42, 0, 0, 0,
977
+ ]);
978
+ expect(() => createPerpSettleFundingInstruction({ marketRecordIndex: 1, targetSeatIndex: 0 })).toThrow(/targetSeatIndex/);
979
+ expect(() => createPerpMarketSetFundingInstruction({
980
+ marketRecordIndex: 1, interestRate: -1, clampSmall: 0, clampBig: 0, premiumMultiplier: 0, impactNotional: 0n,
981
+ })).toThrow(/interestRate/);
982
+ });
983
+
984
+ it('parses the funding round event (type 16)', () => {
985
+ const data = new Uint8Array(8 + 32 + 8 + 8 + 4 + 4 + 8 + 16 + 8);
986
+ const view = new DataView(data.buffer);
987
+ view.setBigUint64(0, BigInt(PERP_EVENT_FUNDING_ROUND), true);
988
+ data.set(key(60), 8); /* market */
989
+ view.setBigInt64(40, -312n, true); /* rate */
990
+ view.setBigInt64(48, -180_000n, true); /* premium_sum */
991
+ view.setUint32(56, 60, true); /* sample_cnt */
992
+ view.setBigUint64(64, 200n, true); /* index_price */
993
+ view.setBigInt64(72, -6_052_800n, true); /* funding_index lo */
994
+ view.setBigInt64(80, -1n, true); /* funding_index hi */
995
+ view.setBigUint64(88, 3_600_000_000_000n, true); /* round_ns */
996
+ const event = parsePerpEvent(data);
997
+ expect(event).toMatchObject({
998
+ variant: 'funding_round',
999
+ market: address(60),
1000
+ rate: -312n,
1001
+ premiumSum: -180_000n,
1002
+ sampleCount: 60,
1003
+ indexPrice: 200n,
1004
+ fundingIndex: -6_052_800n,
1005
+ roundNs: 3_600_000_000_000n,
1006
+ });
1007
+ });
1008
+ });