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 Node SDK.

Legend

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

---

SyncService

Method	Status	Notes
FetchBlock	✅	SyncClient.fetchBlock()
DumpHistory	✅	SyncClient.fetchHistory()
FollowTip	✅	SyncClient.followTip() - handles apply/undo/reset
ReadTip	✅	SyncClient.readTip()

---

QueryService

Method	Status	Notes
ReadParams	✅	QueryClient.readParams()
ReadUtxos	✅	QueryClient.readUtxosByOutputRef()
SearchUtxos	✅	Multiple convenience methods available
ReadData	❌	Not implemented - Read datum by hash
ReadTx	❌	Not implemented - Get transaction by hash
ReadGenesis	✅	QueryClient.readGenesis()
ReadEraSummary	✅	QueryClient.readErasummary()

SearchUtxos Convenience Methods

• ✅ searchUtxosByAddress
• ✅ searchUtxosByPaymentPart
• ✅ searchUtxosByDelegationPart
• ✅ searchUtxosByAsset
• ✅ searchUtxosByAddressWithAsset
• ✅ searchUtxosByPaymentPartWithAsset
• ✅ searchUtxosByDelegationPartWithAsset

---

SubmitService

Method	Status	Notes
EvalTx	⚠️	Implemented but wraps in array - spec changed to single tx
SubmitTx	⚠️	Implemented but wraps in array - spec changed to single tx
WaitForTx	✅	SubmitClient.waitForTx()
ReadMempool	❌	Not implemented - Get mempool snapshot
WatchMempool	✅	Multiple convenience methods available

WatchMempool Convenience Methods

• ✅ watchMempool (all txs)
• ✅ watchMempoolForAddress
• ✅ watchMempoolForPaymentPart
• ✅ watchMempoolForDelegationPart
• ✅ watchMempoolForAsset
• ❌ watchMempoolForMintsAsset - mints_asset pattern not exposed
• ❌ watchMempoolForCertificate - has_certificate pattern not exposed

---

WatchService

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

WatchTx Convenience Methods

• ✅ watchTx (all txs)
• ✅ watchTxForAddress
• ✅ watchTxForPaymentPart
• ✅ watchTxForDelegationPart
• ✅ watchTxForAsset
• ❌ watchTxForMintsAsset - mints_asset pattern not exposed
• ❌ watchTxForCertificate - has_certificate pattern not exposed

WatchTxResponse Actions

• ✅ apply - handled
• ✅ undo - handled
• ❌ idle - Not handled (new in 0.18.x - no-match signal for block progress)

---

TxPattern Coverage (for Watch/Mempool predicates)

Pattern Field	Status	Notes
consumes	❌	Not exposed via convenience methods
produces	❌	Not exposed via convenience methods
has_address	✅	exactAddress, paymentPart, delegationPart
moves_asset	✅	policyId, assetName
mints_asset	❌	Not exposed
has_certificate	❌	Not exposed

---

Summary

Missing Features (Priority)

1. ReadData - Read datum by hash
2. ReadTx - Get transaction by hash
3. ReadMempool - Get mempool snapshot
4. idle action handling - Block progress signal in WatchTx

Breaking Changes to Address

1. SubmitTx and EvalTx changed from repeated tx to single tx in spec
   • Current implementation wraps single tx in array (lines 349, 357)
   • Need to update to match new spec signature

Pattern Enhancements

1. Expose mints_asset pattern for mint/burn filtering
2. Expose has_certificate pattern for certificate filtering
3. Expose consumes/produces patterns for input/output filtering

---

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 (node-sdk main branch):

   • src/cardano.ts - Main Cardano client implementations

Analysis Process

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

• A corresponding method exists in the SDK client classes
• 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);              // ❌ Not in SDK
  rpc ReadGenesis(ReadGenesisRequest) returns (ReadGenesisResponse);
  rpc ReadEraSummary(ReadEraSummaryRequest) returns (ReadEraSummaryResponse);

SubmitService:
  rpc EvalTx(EvalTxRequest) returns (EvalTxResponse);
  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/cardano.ts):

• QueryClient class (lines 190-330): Has readParams, readUtxosByOutputRef, searchUtxosByMatch, readGenesis, readErasummary - missing readData, readTx
• SubmitClient class (lines 332-425): Has submitTx, evalTx, waitForTx, watchMempool* - missing readMempool
• toTxEvent function (lines 53-61): Only handles apply and undo cases, not idle