Feature Support Tracking: UTxO RPC Spec v0.18.1

[Mercurial]

UTxO RPC Spec v0.18.1 Feature Support Tracking

This issue tracks which features from the UTxO RPC spec v0.18.1 are currently implemented in the Rust SDK.

Legend

• ✅ Implemented
• ❌ Not Implemented
• ⚠️ Needs Update (breaking change in spec)

---

SyncService

Method	Status	Notes
FetchBlock	✅	SyncClient::fetch_block()
DumpHistory	✅	SyncClient::dump_history()
FollowTip	✅	SyncClient::follow_tip() - returns LiveTip stream
ReadTip	✅	SyncClient::read_tip()

TipEvent Actions

• ✅ Apply - handled
• ✅ Undo - handled
• ✅ Reset - handled

---

QueryService

Method	Status	Notes
ReadParams	✅	QueryClient::read_params()
ReadUtxos	✅	QueryClient::read_utxos()
SearchUtxos	✅	QueryClient::search_utxos() / match_utxos()
ReadData	❌	Not implemented - Read datum by hash
ReadTx	✅	QueryClient::read_tx()
ReadGenesis	✅	QueryClient::read_genesis()
ReadEraSummary	✅	QueryClient::read_era_summary()

---

SubmitService

Method	Status	Notes
EvalTx	❌	Not implemented
SubmitTx	⚠️	Takes Vec<B>, returns Vec<NativeBytes> - spec changed to single tx
WaitForTx	✅	SubmitClient::wait_for_tx()
ReadMempool	❌	Not implemented - Get mempool snapshot
WatchMempool	✅	SubmitClient::watch_mempool() - returns MempoolStream

---

WatchService

Method	Status	Notes
WatchTx	⚠️	Implemented but idle action not handled

WatchTxResponse Actions

• ✅ Apply - handled
• ✅ Undo - handled
• ❌ Idle - Returns Ok(None) instead of propagating (new in 0.18.x)

---

Design Notes

Generic Chain Trait

The Rust SDK uses a generic Chain trait that allows supporting multiple blockchains:

pub trait Chain {
    type ParsedBlock;
    type ParsedTx;
    type ParsedUtxo;
    type Intersect;
    type UtxoPattern;
    // ...
}

Currently only Cardano implements this trait. This is a good design that allows future multi-chain support.

Type Aliases

• CardanoSyncClient = SyncClient<Cardano>
• CardanoQueryClient = QueryClient<Cardano>
• CardanoSubmitClient = SubmitClient<Cardano>
• CardanoWatchClient = WatchClient<Cardano>

---

Summary

Missing Features (Priority)

1. EvalTx - Evaluate transaction without submitting (get execution units)
2. ReadData - Read datum by hash
3. ReadMempool - Get mempool snapshot
4. Idle action handling - Block progress signal in WatchTx

Breaking Changes to Address

1. SubmitTx changed from repeated tx to single tx in spec
   • Current implementation: submit_tx(txs: Vec<B>) -> Result<Vec<NativeBytes>>
   • Spec expects: single tx in, single ref out
   • Consider adding submit_single_tx() or updating signature

WatchedTx Idle Handling

In WatchedTxStream::event() (lib.rs:625-646), the idle action case is missing:

match res.action {
    Some(Action::Apply(tx)) => { ... }
    Some(Action::Undo(tx)) => { ... }
    // Missing: Some(Action::Idle(block_ref)) => { ... }
    None => Ok(None),
}

The idle action provides a no-match signal with a BlockRef, useful for:

• Tracking chain progress when no matching txs are found
• Implementing reliable synchronization logic

---

cc @SonicSwordcane

[Mercurial]

Methodology

This feature matrix was established by comparing:

1. Spec Proto Files (utxorpc/spec v0.18.1):

   • proto/utxorpc/v1alpha/sync/sync.proto - SyncService definition
   • proto/utxorpc/v1alpha/query/query.proto - QueryService definition
   • proto/utxorpc/v1alpha/submit/submit.proto - SubmitService definition
   • proto/utxorpc/v1alpha/watch/watch.proto - WatchService definition
   • proto/utxorpc/v1alpha/cardano/cardano.proto - Cardano-specific types (TxPattern, TxOutputPattern, etc.)

2. SDK Source Code (rust-sdk main branch):

   • src/lib.rs - All client implementations

Analysis Process

For each RPC method defined in the proto files, I checked whether:

• A corresponding method exists in the SDK client structs
• The method signature matches the proto definition
• All action types in streaming responses are handled

Key Files Reviewed

Spec (v0.18.1):

QueryService:
  rpc ReadParams(ReadParamsRequest) returns (ReadParamsResponse);
  rpc ReadUtxos(ReadUtxosRequest) returns (ReadUtxosResponse);
  rpc SearchUtxos(SearchUtxosRequest) returns (SearchUtxosResponse);
  rpc ReadData(ReadDataRequest) returns (ReadDataResponse);        // ❌ Not in SDK
  rpc ReadTx(ReadTxRequest) returns (ReadTxResponse);
  rpc ReadGenesis(ReadGenesisRequest) returns (ReadGenesisResponse);
  rpc ReadEraSummary(ReadEraSummaryRequest) returns (ReadEraSummaryResponse);

SubmitService:
  rpc EvalTx(EvalTxRequest) returns (EvalTxResponse);              // ❌ Not in SDK
  rpc SubmitTx(SubmitTxRequest) returns (SubmitTxResponse);
  rpc WaitForTx(WaitForTxRequest) returns (stream WaitForTxResponse);
  rpc ReadMempool(ReadMempoolRequest) returns (ReadMempoolResponse);  // ❌ Not in SDK
  rpc WatchMempool(WatchMempoolRequest) returns (stream WatchMempoolResponse);

WatchTxResponse:
  oneof action {
    AnyChainTx apply = 1;
    AnyChainTx undo = 2;
    BlockRef idle = 3;   // ❌ Not handled in SDK
  }

SDK (src/lib.rs):

• QueryClient impl (lines 438-549): Has read_params, read_genesis, read_era_summary, read_utxos, search_utxos, match_utxos, read_tx - missing read_data
• SubmitClient impl (lines 557-599): Has submit_tx, wait_for_tx, watch_mempool - missing eval_tx, read_mempool
• WatchedTxStream::event() (lines 624-647): Only handles Apply and Undo cases, idle returns Ok(None):

  match res.action {
      Some(spec::watch::watch_tx_response::Action::Apply(tx)) => { ... }
      Some(spec::watch::watch_tx_response::Action::Undo(tx)) => { ... }
      None => Ok(None),  // idle case falls through here
  }