memq.proto

syntax = "proto3";

package memq;

// The primary query interface for memq.
//
// All unary RPCs target sub-millisecond latency on localhost. Streaming RPCs
// push updates at a client-specified interval until the client disconnects.
// Every RPC returns UNAVAILABLE while the initial mempool sync is in progress.
service MemqService {
  // Blended fee estimate for a confirmation target (1–1008 blocks).
  // Uses live mempool simulation for targets ≤ 6, Bitcoin Core's
  // estimatesmartfee for targets > 6. Confidence is halved when degraded.
  rpc EstimateFee(EstimateFeeRequest) returns (EstimateFeeResponse);

  // Current mempool summary: transaction count, total vsize, total fees.
  rpc GetMempoolStats(MempoolStatsRequest) returns (MempoolStatsResponse);

  // Fee-rate distribution histogram. num_buckets is clamped to [1, 256].
  // Responses are cached for 500 ms when the bucket count matches.
  rpc GetFeeHistogram(FeeHistogramRequest) returns (FeeHistogramResponse);

  // Cluster-aware block assembly simulation. num_blocks is clamped to [1, 144].
  // Responses are cached for 500 ms when the block count matches.
  rpc SimulateBlocks(SimulateBlocksRequest) returns (SimulateBlocksResponse);

  // Look up a single mempool transaction by hex-encoded txid.
  // Returns found=false (with zeroed fields) for unknown txids.
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);

  // Server-streaming fee estimates at a configurable interval.
  // interval_ms is clamped to [100, 60000]. Stream runs until client disconnects.
  rpc StreamFeeEstimates(StreamFeeEstimatesRequest) returns (stream EstimateFeeResponse);

  // Probabilistic confirmation time distribution for a given fee rate.
  // Returns marginal and cumulative probabilities for each block target.
  // max_blocks is clamped to [1, 25].
  rpc EstimateConfirmationDistribution(ConfirmationDistributionRequest) returns (ConfirmationDistributionResponse);

  // CPFP-aware child fee estimation. Calculates the fee rate a child
  // transaction must pay to pull the parent's ancestor package into a
  // target block. Returns NOT_FOUND if the parent is not in the mempool.
  rpc EstimateCpfpFee(CpfpFeeRequest) returns (CpfpFeeResponse);

  // Snapshot of fee pressure metrics: surge score, inflow rate, RBF rate,
  // floor delta, and mempool growth rate.
  rpc GetFeePressure(FeePressureRequest) returns (FeePressureResponse);

  // Server-streaming fee pressure updates.
  // interval_ms is clamped to [500, 60000]. Stream runs until client disconnects.
  rpc StreamFeePressure(StreamFeePressureRequest) returns (stream FeePressureResponse);
}

message StreamFeeEstimatesRequest {
  // Target number of blocks for confirmation
  uint32 target_blocks = 1;
  // Interval between updates in milliseconds (clamped to [100, 60000])
  uint32 interval_ms = 2;
}

message EstimateFeeRequest {
  // Target number of blocks for confirmation (1–1008).
  uint32 target_blocks = 1;
}

// Which data source produced the recommended fee rate.
enum EstimateSource {
  // Derived from live mempool simulation (targets ≤ 6).
  ESTIMATE_SOURCE_MEMPOOL = 0;
  // Derived from Bitcoin Core's historical estimatesmartfee (targets > 6).
  ESTIMATE_SOURCE_BITCOIN_CORE = 1;
  // Mempool simulation used as fallback because Core was unavailable.
  ESTIMATE_SOURCE_MEMPOOL_FALLBACK = 2;
}

message EstimateFeeResponse {
  // Recommended fee rate in sat/vB for the requested target.
  double fee_rate_sat_per_vb = 1;
  // Confidence score [0.0, 1.0]. Lower when the mempool is thin (<100 txs)
  // or the engine is in a degraded state (halved on ZMQ gap).
  double confidence = 2;
  // Which data source produced fee_rate_sat_per_vb.
  EstimateSource source = 3;
  // Fee rate from live mempool simulation (always computed, regardless of source).
  double mempool_fee_rate_sat_per_vb = 4;
  // Fee rate from Bitcoin Core's estimatesmartfee (0.0 if not queried for this target).
  double core_fee_rate_sat_per_vb = 5;
}

message MempoolStatsRequest {}

message MempoolStatsResponse {
  // Number of transactions currently in the mempool mirror.
  uint64 tx_count = 1;
  // Total virtual size of all mempool transactions (vbytes).
  uint64 total_vsize_bytes = 2;
  // Total fees of all mempool transactions (satoshis).
  uint64 total_fees_sat = 3;
}

message FeeHistogramRequest {
  uint32 num_buckets = 1;
}

message FeeHistogramResponse {
  repeated FeeHistogramBucket buckets = 1;
}

message FeeHistogramBucket {
  double min_fee_rate = 1;
  double max_fee_rate = 2;
  uint64 tx_count = 3;
  uint64 total_vsize = 4;
}

message SimulateBlocksRequest {
  uint32 num_blocks = 1;
}

message SimulateBlocksResponse {
  repeated SimulatedBlock blocks = 1;
}

message SimulatedBlock {
  // Relative block number (1 = next block, 2 = block after, etc.).
  uint32 block_number = 1;
  // Number of transactions projected for this block.
  uint64 tx_count = 2;
  // Total virtual size of the projected block (vbytes, ≤ 1,000,000).
  uint64 total_vsize = 3;
  // Total fees collected by the miner in this block (satoshis).
  uint64 total_fees = 4;
  // Lowest fee rate (sat/vB) of any transaction included in this block.
  double min_fee_rate = 5;
}

message GetTransactionRequest {
  // Hex-encoded txid
  string txid = 1;
}

message GetTransactionResponse {
  // Whether the transaction was found in the mempool.
  bool found = 1;
  // Individual fee rate in sat/vB (not cluster-adjusted).
  double fee_rate = 2;
  // Absolute fee in satoshis.
  uint64 fee = 3;
  // Virtual size in vbytes (BIP141).
  uint64 vsize = 4;
  // Weight in weight units.
  uint64 weight = 5;
  // Whether the transaction signals BIP125 RBF.
  bool signals_rbf = 6;
  // Unix nanosecond timestamp when memq first observed this transaction.
  uint64 received_at = 7;
  // Hex-encoded txids of direct in-mempool parent transactions.
  repeated string depends = 8;
  // Hex-encoded txids of direct in-mempool child transactions.
  repeated string spent_by = 9;
  // Number of ancestors in the dependency graph (including self).
  uint32 ancestor_count = 10;
  // Number of descendants in the dependency graph (including self).
  uint32 descendant_count = 11;
}

// --- Probabilistic Confirmation Distribution ---

message ConfirmationDistributionRequest {
  // Fee rate to evaluate (sat/vB)
  double fee_rate_sat_per_vb = 1;
  // Maximum number of blocks to project (clamped to [1, 25])
  uint32 max_blocks = 2;
}

message ConfirmationDistributionResponse {
  repeated ConfirmationPoint points = 1;
}

message ConfirmationPoint {
  // Block target (1 = next block, 2 = block after, etc.).
  uint32 block_target = 1;
  // Probability of confirming in exactly this block (not earlier).
  double marginal_probability = 2;
  // Probability of confirming in this block or any earlier block.
  // Guaranteed monotonically non-decreasing across points.
  double cumulative_probability = 3;
}

// --- CPFP Fee Estimation ---

message CpfpFeeRequest {
  // Hex-encoded txid of the stuck parent
  string parent_txid = 1;
  // Target block for confirmation
  uint32 target_blocks = 2;
  // Virtual size of the planned child transaction (vbytes)
  uint64 child_vsize = 3;
}

message CpfpFeeResponse {
  // Fee rate (sat/vB) the child must pay. Zero when already_sufficient.
  double required_child_fee_rate = 1;
  // Absolute fee (satoshis) the child must carry. Zero when already_sufficient.
  uint64 required_child_fee = 2;
  // Fee rate (sat/vB) required for the combined package to enter the target block.
  double target_fee_rate = 3;
  // Virtual size of the ancestor package (parent + ancestors, excluding child) in vbytes.
  uint64 package_vsize = 4;
  // Total fees of the ancestor package (parent + ancestors) in satoshis.
  uint64 package_fee = 5;
  // Current effective fee rate of the ancestor package (sat/vB).
  double package_fee_rate = 6;
  // True if the ancestor package already meets the target fee rate — no child needed.
  bool already_sufficient = 7;
  // Number of transactions in the ancestor package (including the parent itself).
  uint64 package_ancestor_count = 8;
}

// --- Fee Pressure / Surge Detection ---

message FeePressureRequest {}

message FeePressureResponse {
  // Normalized surge score [-1.0, 1.0]. Positive = rising fees, negative = falling.
  // Computed from the divergence between short and long EMA of high-fee inflow.
  double surge_score = 1;
  // Smoothed inflow rate (vbytes/sec) of transactions above the median fee bucket.
  double high_fee_inflow_vb_per_sec = 2;
  // Smoothed RBF replacement rate (replacements per second).
  double rbf_rate_per_sec = 3;
  // Estimated direction of the next-block fee floor (sat/vB change per block, smoothed).
  double floor_delta_per_block = 4;
  // Smoothed total mempool vsize growth rate (vbytes/sec). Negative = shrinking.
  double mempool_growth_vb_per_sec = 5;
  // Seconds since the last pressure update (tick). Indicates data freshness.
  double age_secs = 6;
}

message StreamFeePressureRequest {
  // Interval between updates in milliseconds (clamped to [500, 60000])
  uint32 interval_ms = 1;
}