[intent-coprocessor]: Price Discovery Protocol

docs/content/developers/intent-gateway/meta.json

@@ -1,5 +1,5 @@
 {
     "title": "Intent Gateway",
-    "pages": ["overview", "placing-orders", "cancelling-orders", "simplex"],
+    "pages": ["overview", "placing-orders", "cancelling-orders", "simplex", "price-submission"],
     "defaultOpen": false
 }

docs/content/developers/intent-gateway/price-submission.mdx

@@ -0,0 +1,126 @@
+---
+title: Price Submission Protocol
+description: Deposit-based price submission system for the intents coprocessor pallet
+---
+
+# Price Submission Protocol
+
+## Overview
+
+The intents system needs on-chain price data for token pairs to function correctly. Rather than relying on external oracles, the protocol allows anyone to submit prices for governance-approved token pairs by putting up a deposit on their first submission. After that initial deposit, updating prices for the same pair is free. The deposit can be reclaimed later through a two-phase withdrawal process, which gives the system time to detect and respond to malicious data before the submitter disappears with their funds.
+
+## Submitting Prices
+
+The `submit_pair_price` extrinsic on the intents coprocessor pallet is the entry point for all price submissions. It accepts a pair ID and a bounded list of price entries. All prices and amount ranges are encoded as U256 values scaled by 10^18, giving 18 decimal places of precision.
+
+Submissions are batched. Each call accepts up to `MaxPriceEntries` entries (a compile-time constant configurable per runtime), where each entry specifies a base token amount range and the corresponding price of the base token in terms of the quote token. This makes it possible to quote different rates for different order sizes in a single transaction. For example, a submitter might quote USDC/CNGN at 1414 for orders between 0 and 999, and 1420 for orders between 1000 and 5000.
+
+Each price entry contains three fields. The `range_start` field is the lower bound of the base token amount range (inclusive). The `range_end` field is the upper bound (also inclusive). The `price` field is the cost of one unit of the base token in terms of the quote token. The pallet validates that `range_start` is less than or equal to `range_end` for every entry and rejects empty submissions. When stored on-chain, each entry becomes a `PriceEntry` that also includes the submission timestamp.
+
+## Deposit Model
+
+On the first price submission for a given account and token pair, a deposit is reserved from the submitter's balance. The deposit amount is set by governance through the `set_price_deposit_amount` extrinsic. After the initial deposit, the submitter can update prices for the same token pair as many times as they want without paying anything further.
+
+This design discourages spam because each new pair requires locking funds, while keeping ongoing price updates free for active participants.
+
+## Two-Phase Withdrawal
+
+Withdrawing a deposit uses a two-phase process through the `withdraw_price_deposit` extrinsic. The first call initiates the withdrawal by recording the unlock block, which is the current block number plus the governance-configured lock duration. No tokens are moved at this point, and the pallet emits a `PriceDepositWithdrawalInitiated` event.
+
+Once the unlock block has been reached, a second call to the same extrinsic completes the withdrawal. The pallet unreserves the tokens, removes the deposit record, and emits a `PriceDepositWithdrawn` event. If the second call is made before the unlock block, it fails with a `DepositStillLocked` error.
+
+The lock duration is measured in blocks and set by governance through `set_price_deposit_lock_duration`. This two-phase model ensures there is always a window during which bad actors can be identified and penalized before they can withdraw their deposit.
+
+## Price Windows and Data Lifecycle
+
+Prices are organized into time-based windows. The window duration is governance-configurable via `PriceWindowDurationValue`, specified in milliseconds.
+
+The `on_initialize` hook runs every block and checks whether the current window has expired. When it has, it resets a `PricesClearedThisWindow` flag to false. Prices from the previous window are not cleared immediately. They persist so that consumers can still read the previous window's data.
+
+On the first new submission in a new window, all price entries across all pairs are cleared before the new entries are stored. This lazy clearing approach avoids the cost of iterating all pairs in `on_initialize` (which would be unbounded weight paid by the block producer) while ensuring stale data is replaced as soon as fresh data arrives. After the first submission clears the data, the global boolean flag ensures subsequent submissions in the same window skip the clearing step entirely.
+
+## Recognized Pairs
+
+Only governance-approved token pairs can receive price submissions. This prevents spam for arbitrary token combinations and keeps storage growth under control. Governance manages pairs through the `add_recognized_pair` and `remove_recognized_pair` extrinsics. Removing a pair also cleans up its associated price data and storage.
+
+## RPC
+
+The `intents_getPairPrices(pair_id)` RPC endpoint returns all price entries for a given token pair. The raw on-chain values (U256 scaled by 10^18) are converted to human-readable decimal strings with fractional precision preserved. For example, an on-chain value of 1414500000000000000000 is returned as the string "1414.5". Each returned entry includes the amount range boundaries (`range_start` and `range_end`), the `price`, and the submission `timestamp` in seconds.
+
+## Simplex Filler Integration
+
+The simplex filler submits price updates automatically as part of the FX strategy. When the filler starts and a `hyperfx` strategy is configured with a `pairId`, the FX strategy spawns a periodic task that converts its ask price curve into on-chain price entries and submits them via `IntentsCoprocessor.submitPairPrice()`. There is no separate price configuration section; the prices come directly from the strategy's existing ask price curve, which is the same curve used to evaluate order profitability.
+
+The task runs on a configurable interval (defaulting to every 5 minutes). An initial submission is triggered shortly after startup so that prices are available immediately rather than waiting for the first interval to elapse.
+
+### Configuration
+
+Price submission is enabled by adding a `pairId` to the `hyperfx` strategy in the filler TOML configuration file. The ask price curve points are converted into price entries automatically, where each point on the curve defines a price range.
+
+```toml
+[[strategies]]
+type = "hyperfx"
+pairId = "0x..."                    # On-chain pair ID (keccak256 of base_address ++ quote_address)
+priceSubmissionIntervalSeconds = 300 # How often to submit prices (default: 300 = 5 minutes)
+maxOrderUsd = "5000"
+
+[[strategies.askPriceCurve]]
+amount = "0"
+price = "1414"
+
+[[strategies.askPriceCurve]]
+amount = "1000"
+price = "1420"
+
+[[strategies.bidPriceCurve]]
+amount = "0"
+price = "1500"
+
+[[strategies.bidPriceCurve]]
+amount = "1000"
+price = "1490"
+
+[strategies.exoticTokenAddresses]
+"EVM-56" = "0xabc..."
+```
+
+The ask curve points are sorted by amount and each point becomes a price entry. The range for each entry spans from that point's amount to just below the next point's amount. The last point extends to a large upper bound. Amounts and prices are converted to 18-decimal format before submission.
+
+The first submission for each pair will reserve a deposit from the substrate account. Subsequent updates to the same pair are free. When a filler wants to reclaim their deposit, they call `withdrawPriceDeposit` once to initiate the withdrawal (which records the unlock block), then call it again after the governance-configured lock duration has elapsed to unreserve the tokens.
+
+### SDK Usage
+
+The `IntentsCoprocessor` class in `@hyperbridge/sdk` exposes methods for price submission and deposit withdrawal directly. These methods accept raw 18-decimal bigint values.
+
+```typescript
+import { IntentsCoprocessor } from "@hyperbridge/sdk"
+import { parseUnits } from "viem"
+
+const coprocessor = await IntentsCoprocessor.connect(wsUrl, substratePrivateKey)
+
+// Submit prices for a token pair (values in 18-decimal format)
+await coprocessor.submitPairPrice("0x...", [
+  { rangeStart: parseUnits("0", 18), rangeEnd: parseUnits("999", 18), price: parseUnits("1414", 18) },
+  { rangeStart: parseUnits("1000", 18), rangeEnd: parseUnits("5000", 18), price: parseUnits("1420", 18) },
+])
+
+// Withdraw deposit (two-phase):
+// Phase 1: initiate withdrawal (records unlock block)
+await coprocessor.withdrawPriceDeposit("0x...")
+// Phase 2: complete withdrawal after unlock block is reached
+await coprocessor.withdrawPriceDeposit("0x...")
+```
+
+## Governance Parameters
+
+The protocol has several parameters that are stored on-chain and updatable through governance extrinsics.
+
+`PriceWindowDurationValue` controls the length of each price window in milliseconds. When a window expires, the next submission triggers a lazy clear of all existing price data.
+
+`PriceDepositAmount` is the amount reserved from a submitter's balance on their first price submission for a given token pair. This deposit stays locked until explicitly withdrawn through the two-phase process.
+
+`PriceDepositLockDuration` determines how many blocks the deposit remains locked after a withdrawal is initiated. The submitter must wait this many blocks before completing the withdrawal.
+
+`MaxPriceEntries` is a compile-time constant (configurable per runtime) that limits how many price entries can be included in a single submission.
+
+Recognized token pairs are managed through `add_recognized_pair` and `remove_recognized_pair`. Only pairs that have been explicitly added by governance can receive price submissions.

modules/pallets/intents-coprocessor/Cargo.toml

@@ -28,7 +28,9 @@ anyhow = { workspace = true }
 alloy-primitives = { workspace = true }
 alloy-sol-macro = { workspace = true }
 alloy-sol-types = { workspace = true }
+hex-literal = { workspace = true }
 
+crypto-utils = { workspace = true }
 ismp = { workspace = true }
 pallet-ismp = { workspace = true }
 
@@ -49,6 +51,7 @@ std = [
     "scale-info/std",
     "anyhow/std",
     "alloy-primitives/std",
+    "crypto-utils/std",
     "sp-io/std",
     "pallet-ismp/std",
 ]

modules/pallets/intents-coprocessor/rpc/Cargo.toml

@@ -13,6 +13,7 @@ log = { workspace = true, default-features = true }
 tokio = { workspace = true, features = ["sync", "time"] }
 futures = { workspace = true }
 hex = { workspace = true, default-features = true }
+primitive-types = { workspace = true, default-features = true }
 pallet-intents-coprocessor = { workspace = true, default-features = true }
 
 [dependencies.polkadot-sdk]

modules/pallets/intents-coprocessor/rpc/src/lib.rs

@@ -53,6 +53,18 @@ pub struct RpcBidInfo {
 	pub user_op: Vec<u8>,
 }
 
+/// A single price entry returned by the RPC.
+/// Amounts and prices are human-readable (divided by 10^18 from on-chain storage).
+#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
+pub struct RpcPriceEntry {
+	/// The amount threshold for this price point
+	pub amount: String,
+	/// The price at this amount
+	pub price: String,
+	/// The filler (submitter) address
+	pub filler: String,
+}
+
 impl Ord for RpcBidInfo {
 	fn cmp(&self, other: &Self) -> std::cmp::Ordering {
 		self.filler.cmp(&other.filler)
@@ -154,10 +166,39 @@ impl BidCache {
 	}
 }
 
+/// Format a U256 value with the given number of decimal places into a human-readable
+/// decimal string, preserving fractional digits and trimming trailing zeros.
+/// e.g. format_u256_decimals(U256::from(1_414_500_000_000_000_000_000u128), 18) => "1414.5"
+fn format_u256_decimals(value: primitive_types::U256, decimals: u32) -> String {
+	let divisor = primitive_types::U256::from(10u64).pow(primitive_types::U256::from(decimals));
+	let integer_part = value / divisor;
+	let remainder = value % divisor;
+
+	if remainder.is_zero() {
+		return integer_part.to_string();
+	}
+
+	// Pad remainder to full `decimals` width, then trim trailing zeros
+	let frac = format!("{:0>width$}", remainder, width = decimals as usize);
+	let frac = frac.trim_end_matches('0');
+	format!("{integer_part}.{frac}")
+}
+
 fn runtime_error_into_rpc_error(e: impl std::fmt::Display) -> ErrorObjectOwned {
 	ErrorObject::owned(9877, format!("{e}"), None::<String>)
 }
 
+/// Construct the full storage key for a `StorageMap` entry with `Blake2_128Concat` hasher.
+fn storage_map_key(pallet: &[u8], storage: &[u8], map_key: &H256) -> Vec<u8> {
+	let mut key = Vec::new();
+	key.extend_from_slice(&sp_core::hashing::twox_128(pallet));
+	key.extend_from_slice(&sp_core::hashing::twox_128(storage));
+	let map_key_bytes = map_key.as_bytes();
+	key.extend_from_slice(&sp_core::hashing::blake2_128(map_key_bytes));
+	key.extend_from_slice(map_key_bytes);
+	key
+}
+
 /// Construct the storage key prefix for iterating all fillers in the on-chain
 /// `Bids` double-map for a given order commitment.
 fn bids_storage_prefix(commitment: &H256) -> Vec<u8> {
@@ -176,6 +217,10 @@ pub trait IntentsApi {
 	#[method(name = "intents_getBidsForOrder")]
 	fn get_bids_for_order(&self, commitment: H256) -> RpcResult<Vec<RpcBidInfo>>;
 
+	/// Get all prices for a token pair
+	#[method(name = "intents_getPairPrices")]
+	fn get_pair_prices(&self, pair_id: H256) -> RpcResult<Vec<RpcPriceEntry>>;
+
 	#[subscription(name = "intents_subscribeBids" => "intents_bidNotification", unsubscribe = "intents_unsubscribeBids", item = RpcBidInfo)]
 	async fn subscribe_bids(&self, commitment: Option<H256>) -> SubscriptionResult;
 }
@@ -259,6 +304,32 @@ where
 		Ok(bids.into_iter().collect())
 	}
 
+	fn get_pair_prices(&self, pair_id: H256) -> RpcResult<Vec<RpcPriceEntry>> {
+		let best_hash = self.client.info().best_hash;
+
+		let key = storage_map_key(b"IntentsCoprocessor", b"Prices", &pair_id);
+		let storage_key = sp_core::storage::StorageKey(key);
+
+		let data = match self.client.storage(best_hash, &storage_key) {
+			Ok(Some(data)) => data.0,
+			_ => return Ok(Vec::new()),
+		};
+
+		use pallet_intents_coprocessor::types::PriceEntry;
+
+		match BTreeSet::<PriceEntry>::decode(&mut &data[..]) {
+			Ok(entries) => Ok(entries
+				.into_iter()
+				.map(|entry| RpcPriceEntry {
+					amount: format_u256_decimals(entry.amount, 18),
+					price: format_u256_decimals(entry.price, 18),
+					filler: format!("0x{}", hex::encode(entry.filler.as_bytes())),
+				})
+				.collect()),
+			Err(_) => Ok(Vec::new()),
+		}
+	}
+
 	async fn subscribe_bids(
 		&self,
 		pending: PendingSubscriptionSink,