logos-blockchain/lez-programs
1
0
Fork 0
mirror of https://github.com/logos-blockchain/lez-programs.git synced 2026-06-29 11:39:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
lez-programs/artifacts/twap_oracle-idl.json

271 lines
5.3 KiB
JSON
Raw Normal View History

chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
{
"version": "0.1.0",
"name": "twap_oracle",
"instructions": [
{
feat(twap-oracle): implement CreatePriceObservations instruction Adds the CreatePriceObservations instruction to the TWAP oracle program. The instruction initialises a PriceObservations PDA for a given price source account and time window, writing the initial tick and timestamp as the first entry. Key design decisions: - Per-window accounts: each (price_source, window_duration) pair maps to a distinct PriceObservations PDA. The window duration is baked into the PDA seed so a single price source can support multiple TWAP windows (24h, 7d, 30d) at independent sampling rates without sharing a buffer. - window_duration not stored on struct: it is implicit in the PDA address. Any reader that located the account already knows the window duration used to derive it. Storing it would be redundant. - Authorization is implicit: the PriceObservations PDA is derived from the price source account ID, so is_authorized = true on the price source proves the caller controls it without a redundant authority field. - Impersonation is prevented by the PDA check: passing a controlled price source with a victim's observations account ID fails immediately because the computed PDA (from the attacker's source) does not match. Closes #126
2026-05-28 10:35:05 +02:00
"name": "create_price_observations",
"accounts": [
{
"name": "price_observations",
"writable": false,
"signer": false,
"init": false
},
{
"name": "price_source",
"writable": false,
"signer": false,
"init": false
},
{
"name": "clock",
"writable": false,
"signer": false,
"init": false
}
],
"args": [
{
"name": "initial_tick",
"type": "i32"
},
{
"name": "window_duration",
"type": "u64"
}
]
feat(twap-oracle): implement CreateOraclePriceAccount instruction Adds the CreateOraclePriceAccount instruction to the TWAP oracle program. The instruction initialises a canonical OraclePriceAccount PDA for a given price source and time window, seeding it with a non-zero initial price and the current block timestamp so the account is immediately valid to consumers. - PDA mirrors PriceObservations: derived from (oracle_program_id, price_source_id, window_duration) with a distinct seed constant, so each (source, window) pair maps to a distinct oracle price account that cannot collide with its corresponding observations account. - source_id is not a parameter: it is always set to price_source.account_id. Accepting it as a free parameter would allow callers to register a price account that claims to represent a source it does not control. Deriving it from the authorized price source account closes that vector entirely. - Authorization follows the same model as CreatePriceObservations: is_authorized = true on the price source proves the caller controls it; the PDA check ensures the supplied oracle price account address is the one derived from that specific source and window. - The initial timestamp is read from the canonical 1-block LEZ clock (CLOCK_01_PROGRAM_ACCOUNT_ID), never from a caller-supplied value. The clock account_id is asserted, so a caller cannot substitute an account they control to forge the seeding timestamp. - A zero price or zero timestamp is rejected at creation. Both are the "no valid price" sentinel consumers treat as unset, so an account must never be created in that state; the instruction asserts a non-zero initial_price and a non-zero clock timestamp. - initial_price is a Q64.64 fixed-point value (real price = initial_price / 2^64), matching the oracle price representation. The non-zero check rejects the sentinel but cannot validate scale — supplying a correctly-scaled value is the caller's responsibility. Closes #129
2026-05-28 20:42:59 +02:00
},
{
"name": "create_oracle_price_account",
"accounts": [
{
"name": "oracle_price_account",
"writable": false,
"signer": false,
"init": false
},
{
"name": "price_source",
"writable": false,
"signer": false,
"init": false
},
{
"name": "clock",
"writable": false,
"signer": false,
"init": false
}
],
"args": [
{
"name": "base_asset",
"type": "account_id"
},
{
"name": "quote_asset",
"type": "account_id"
},
{
"name": "initial_price",
"type": "u128"
},
{
"name": "window_duration",
"type": "u64"
}
]
feat(twap-oracle): implement CreateCurrentTickAccount and UpdateCurrentTick Add CurrentTickAccount — an oracle-owned PDA (one per price source) that holds the latest raw tick written by the price source and a timestamp. The price source calls UpdateCurrentTick after each price-changing operation; anyone can then call RecordTick (upcoming) to advance the PriceObservations accumulator without requiring the price source to be present. PDA is derived from price_source_id only (no window) since a single current tick serves all time windows. Add price_to_tick(price: u128) -> i32 to twap_oracle_core: isqrt(price << 128) -> sqrtPriceX96 -> get_tick_at_sqrt_ratio. The sqrtPriceX96 is clamped to >= MIN_SQRT_RATIO so a zero/dust price maps to MIN_TICK rather than erroring. Add a pure-integer integer_sqrt(U256) (bit-by-bit, no floating point): ruint's root is gated behind its std feature and seeds with f64, neither available in the guest. Uses wrapping_shr for the digit loop (checked_shr rejects the intended lossy shifts). Pull in uniswap_v3_math (for get_tick_at_sqrt_ratio) and alloy-primitives (U256), with ruint pinned to =1.17.0 — 1.18 raised its MSRV to rustc 1.90, above the risc0 guest toolchain's 1.88.
2026-05-29 11:02:01 +02:00
},
{
"name": "create_current_tick_account",
"accounts": [
{
"name": "current_tick_account",
"writable": false,
"signer": false,
"init": false
},
{
"name": "price_source",
"writable": false,
"signer": false,
"init": false
},
{
"name": "clock",
"writable": false,
"signer": false,
"init": false
}
],
"args": [
{
"name": "initial_price",
"type": "u128"
}
]
},
feat(twap-oracle): implement RecordTick instruction Add RecordTick — a permissionless instruction that reads the current tick from a CurrentTickAccount and advances a PriceObservations ring buffer. Authorization is implicit: both PDAs are verified against price_source_id, so the tick can only have been written by whoever controls that price source. A sampling guard silently no-ops if less than `window_duration / OBSERVATIONS_CAPACITY`` ms have elapsed, allowing keepers to call blindly on every block. Tick-delta truncation clamps the per-observation delta to `MAX_TICK_DELTA (9 116)` before advancing tick_cumulative, with last_recorded_tick tracking the untruncated position for the next delta. Also switches ObservationEntry.tick_cumulative to use elapsed milliseconds rather than seconds. Closes #116
2026-06-02 11:40:28 +02:00
{
"name": "record_tick",
"accounts": [
{
"name": "price_observations",
"writable": false,
"signer": false,
"init": false
},
{
"name": "current_tick_account",
"writable": false,
"signer": false,
"init": false
},
{
"name": "clock",
"writable": false,
"signer": false,
"init": false
}
],
"args": [
{
"name": "price_source_id",
"type": "account_id"
},
{
"name": "window_duration",
"type": "u64"
}
]
},
feat(twap-oracle): implement CreateCurrentTickAccount and UpdateCurrentTick Add CurrentTickAccount — an oracle-owned PDA (one per price source) that holds the latest raw tick written by the price source and a timestamp. The price source calls UpdateCurrentTick after each price-changing operation; anyone can then call RecordTick (upcoming) to advance the PriceObservations accumulator without requiring the price source to be present. PDA is derived from price_source_id only (no window) since a single current tick serves all time windows. Add price_to_tick(price: u128) -> i32 to twap_oracle_core: isqrt(price << 128) -> sqrtPriceX96 -> get_tick_at_sqrt_ratio. The sqrtPriceX96 is clamped to >= MIN_SQRT_RATIO so a zero/dust price maps to MIN_TICK rather than erroring. Add a pure-integer integer_sqrt(U256) (bit-by-bit, no floating point): ruint's root is gated behind its std feature and seeds with f64, neither available in the guest. Uses wrapping_shr for the digit loop (checked_shr rejects the intended lossy shifts). Pull in uniswap_v3_math (for get_tick_at_sqrt_ratio) and alloy-primitives (U256), with ruint pinned to =1.17.0 — 1.18 raised its MSRV to rustc 1.90, above the risc0 guest toolchain's 1.88.
2026-05-29 11:02:01 +02:00
{
"name": "update_current_tick",
"accounts": [
{
"name": "current_tick_account",
"writable": false,
"signer": false,
"init": false
},
{
"name": "price_source",
"writable": false,
"signer": false,
"init": false
},
{
"name": "clock",
"writable": false,
"signer": false,
"init": false
}
],
"args": [
{
"name": "price",
"type": "u128"
}
]
chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
}
],
"accounts": [
feat(twap-oracle): implement CreatePriceObservations instruction Adds the CreatePriceObservations instruction to the TWAP oracle program. The instruction initialises a PriceObservations PDA for a given price source account and time window, writing the initial tick and timestamp as the first entry. Key design decisions: - Per-window accounts: each (price_source, window_duration) pair maps to a distinct PriceObservations PDA. The window duration is baked into the PDA seed so a single price source can support multiple TWAP windows (24h, 7d, 30d) at independent sampling rates without sharing a buffer. - window_duration not stored on struct: it is implicit in the PDA address. Any reader that located the account already knows the window duration used to derive it. Storing it would be redundant. - Authorization is implicit: the PriceObservations PDA is derived from the price source account ID, so is_authorized = true on the price source proves the caller controls it without a redundant authority field. - Impersonation is prevented by the PDA check: passing a controlled price source with a victim's observations account ID fails immediately because the computed PDA (from the attacker's source) does not match. Closes #126
2026-05-28 10:35:05 +02:00
{
"name": "PriceObservations",
"type": {
"kind": "struct",
"fields": [
{
"name": "price_source_id",
"type": "account_id"
},
{
"name": "write_index",
"type": "u32"
},
{
"name": "total_entries",
"type": "u64"
},
{
"name": "last_recorded_tick",
"type": "i32"
},
{
"name": "entries",
"type": {
"vec": {
"defined": "ObservationEntry"
}
}
}
]
}
},
chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
{
"name": "OraclePriceAccount",
"type": {
"kind": "struct",
"fields": [
{
"name": "base_asset",
"type": "account_id"
},
{
"name": "quote_asset",
"type": "account_id"
},
{
"name": "price",
"type": "u128"
},
{
"name": "timestamp",
"type": "u64"
},
{
"name": "source_id",
feat(twap-oracle): implement CreateOraclePriceAccount instruction Adds the CreateOraclePriceAccount instruction to the TWAP oracle program. The instruction initialises a canonical OraclePriceAccount PDA for a given price source and time window, seeding it with a non-zero initial price and the current block timestamp so the account is immediately valid to consumers. - PDA mirrors PriceObservations: derived from (oracle_program_id, price_source_id, window_duration) with a distinct seed constant, so each (source, window) pair maps to a distinct oracle price account that cannot collide with its corresponding observations account. - source_id is not a parameter: it is always set to price_source.account_id. Accepting it as a free parameter would allow callers to register a price account that claims to represent a source it does not control. Deriving it from the authorized price source account closes that vector entirely. - Authorization follows the same model as CreatePriceObservations: is_authorized = true on the price source proves the caller controls it; the PDA check ensures the supplied oracle price account address is the one derived from that specific source and window. - The initial timestamp is read from the canonical 1-block LEZ clock (CLOCK_01_PROGRAM_ACCOUNT_ID), never from a caller-supplied value. The clock account_id is asserted, so a caller cannot substitute an account they control to forge the seeding timestamp. - A zero price or zero timestamp is rejected at creation. Both are the "no valid price" sentinel consumers treat as unset, so an account must never be created in that state; the instruction asserts a non-zero initial_price and a non-zero clock timestamp. - initial_price is a Q64.64 fixed-point value (real price = initial_price / 2^64), matching the oracle price representation. The non-zero check rejects the sentinel but cannot validate scale — supplying a correctly-scaled value is the caller's responsibility. Closes #129
2026-05-28 20:42:59 +02:00
"type": "account_id"
chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
},
{
"name": "confidence_interval",
"type": "u128"
}
]
}
feat(twap-oracle): implement CreateCurrentTickAccount and UpdateCurrentTick Add CurrentTickAccount — an oracle-owned PDA (one per price source) that holds the latest raw tick written by the price source and a timestamp. The price source calls UpdateCurrentTick after each price-changing operation; anyone can then call RecordTick (upcoming) to advance the PriceObservations accumulator without requiring the price source to be present. PDA is derived from price_source_id only (no window) since a single current tick serves all time windows. Add price_to_tick(price: u128) -> i32 to twap_oracle_core: isqrt(price << 128) -> sqrtPriceX96 -> get_tick_at_sqrt_ratio. The sqrtPriceX96 is clamped to >= MIN_SQRT_RATIO so a zero/dust price maps to MIN_TICK rather than erroring. Add a pure-integer integer_sqrt(U256) (bit-by-bit, no floating point): ruint's root is gated behind its std feature and seeds with f64, neither available in the guest. Uses wrapping_shr for the digit loop (checked_shr rejects the intended lossy shifts). Pull in uniswap_v3_math (for get_tick_at_sqrt_ratio) and alloy-primitives (U256), with ruint pinned to =1.17.0 — 1.18 raised its MSRV to rustc 1.90, above the risc0 guest toolchain's 1.88.
2026-05-29 11:02:01 +02:00
},
{
"name": "CurrentTickAccount",
"type": {
"kind": "struct",
"fields": [
{
"name": "tick",
"type": "i32"
},
{
"name": "last_updated",
"type": "u64"
}
]
}
chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
}
],
feat(twap-oracle): implement CreatePriceObservations instruction Adds the CreatePriceObservations instruction to the TWAP oracle program. The instruction initialises a PriceObservations PDA for a given price source account and time window, writing the initial tick and timestamp as the first entry. Key design decisions: - Per-window accounts: each (price_source, window_duration) pair maps to a distinct PriceObservations PDA. The window duration is baked into the PDA seed so a single price source can support multiple TWAP windows (24h, 7d, 30d) at independent sampling rates without sharing a buffer. - window_duration not stored on struct: it is implicit in the PDA address. Any reader that located the account already knows the window duration used to derive it. Storing it would be redundant. - Authorization is implicit: the PriceObservations PDA is derived from the price source account ID, so is_authorized = true on the price source proves the caller controls it without a redundant authority field. - Impersonation is prevented by the PDA check: passing a controlled price source with a victim's observations account ID fails immediately because the computed PDA (from the attacker's source) does not match. Closes #126
2026-05-28 10:35:05 +02:00
"types": [
{
"name": "ObservationEntry",
"kind": "struct",
"fields": [
{
"name": "timestamp",
"type": "u64"
},
{
"name": "tick_cumulative",
"type": "i64"
}
]
}
],
chore(twap_oracle): scaffold twap_oracle program Closes #114
2026-05-14 00:20:14 -03:00
"instruction_type": "twap_oracle_core::Instruction"
}
Reference in New Issue Copy Permalink