diff --git a/pages/_meta.json b/pages/_meta.json index 491ab3c..9370b94 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -16,7 +16,7 @@ "type": "separator", "title": "Specification" }, - "build": "Build Module", + "query": "Query Module", "submit": "Submit Module", "sync": "Sync Module", "watch": "Watch Module", diff --git a/pages/build/intro.mdx b/pages/build/intro.mdx deleted file mode 100644 index a9a8ffc..0000000 --- a/pages/build/intro.mdx +++ /dev/null @@ -1,51 +0,0 @@ -import { Callout } from "nextra-theme-docs"; - -# Build Module - -The _Build_ module provides an interface for querying the state of the ledger and constructing transactions. - -## Operations - -- `GetChainTip`: This method retrieves the current chain tip, which represents the latest state of the blockchain. -- `GetChainParam`: This method allows clients to request specific chain parameters, providing essential information for transaction construction and validation. -- `GetUtxoByAddress`: This method enables clients to query UTxOs associated with a list of addresses at a specific point in the chain. -- `GetUtxoByRef`: This method allows clients to fetch UTxOs based on their references, which includes the transaction hash and output index, at a specific point in the chain. -- `HoldUtxo`: This method enables clients to hold UTxOs, preventing them from being spent, and receive updates about lost UTxOs in a streaming fashion. - - - The schema details can be found in the [spec reference](spec). - - -## Sequence Example - -```mermaid -%%{init: { 'theme': 'dark' } }%% -sequenceDiagram - actor Client - participant BuildService - - Note over Client,BuildService: query tip to define tx validity params - Client->>+BuildService: GetChainTip - BuildService-->>-Client: - - Note over Client,BuildService: query params to define fees / other criteria - Client->>+BuildService: GetChainParam ([]) - BuildService-->>-Client: [] - - Note over Client,BuildService: query wallet UTxO to balance tx - Client->>+BuildService: GetUtxoByAddress (address, acquire_point) - BuildService-->>-Client: GetUtxoByAddress (items, next_token) - - Note over Client,BuildService: query UTxO by ref to resolve other inputs - Client->>+BuildService: GetUtxoByRef (ref, acquire_point) - BuildService-->>-Client: GetUtxoByRef (items, next_token) - - Note over Client,BuildService: monitor these UTxO because we plan on using them - Client->>BuildService: HoldUtxo (refs) - activate BuildService - BuildService--)Client: - BuildService--)Client: - Client->>Client: construct / sign the Tx - Client->>BuildService: Done - deactivate BuildService -``` diff --git a/pages/build/spec.mdx b/pages/build/spec.mdx deleted file mode 100644 index e2d9122..0000000 --- a/pages/build/spec.mdx +++ /dev/null @@ -1,159 +0,0 @@ -# Build - - - -## AnyChainUtxo - -An evenlope that holds an UTxO from any of compatible chains - -| Field | Type | Label | Description | -| ------- | ----------------------------------------------------------- | ----- | ----------- | -| cardano | [utxorpc.cardano.v1.TxOutput](#utxorpc-cardano-v1-TxOutput) | | | - - - -## ChainParam - -Represents a key-value pair for a chain parameter. - -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ---------------- | -| key | [string](#string) | | Parameter key. | -| value | [bytes](#bytes) | | Parameter value. | - - - -## ChainPoint - -Represents a specific point in the blockchain. - -| Field | Type | Label | Description | -| ------ | ----------------- | ----- | ------------- | -| slot | [uint64](#uint64) | | Slot number. | -| height | [uint64](#uint64) | | Block height. | -| hash | [bytes](#bytes) | | Block hash. | - - - -## GetChainParamRequest - -Request to get specific chain parameters. - -| Field | Type | Label | Description | -| ----- | ----------------- | -------- | ----------------------------- | -| param | [string](#string) | repeated | List of requested parameters. | - - - -## GetChainParamResponse - -Response containing the requested chain parameters. - -| Field | Type | Label | Description | -| ----- | ------------------------------------------ | -------- | ----------------------------------- | -| param | [ChainParam](#utxorpc-state-v1-ChainParam) | repeated | List of requested chain parameters. | - - - -## GetChainTipRequest - -Request to get the current chain tip. - - - -## GetChainTipResponse - -Response containing the current chain tip. - -| Field | Type | Label | Description | -| ----- | ------------------------------------------ | ----- | ------------------ | -| tip | [ChainPoint](#utxorpc-state-v1-ChainPoint) | | Current chain tip. | - - - -## GetUtxoByAddressRequest - -Request to get UTxOs by their associated addresses. - -| Field | Type | Label | Description | -| ------------- | ------------------------------------------ | -------- | --------------------------------- | -| address | [bytes](#bytes) | repeated | List of addresses to query. | -| acquire_point | [ChainPoint](#utxorpc-state-v1-ChainPoint) | | Point in the chain to query from. | - - - -## GetUtxoByAddressResponse - -Response containing the UTxOs associated with the requested addresses. - -| Field | Type | Label | Description | -| ---------- | ---------------------------------------------- | -------- | --------------------- | -| items | [AnyChainUtxo](#utxorpc-state-v1-AnyChainUtxo) | repeated | List of UTxOs. | -| next_token | [string](#string) | | Token for pagination. | - - - -## GetUtxoByRefRequest - -Request to get UTxOs by their references. - -| Field | Type | Label | Description | -| ------------- | ------------------------------------------ | -------- | --------------------------------- | -| ref | [UtxoRef](#utxorpc-state-v1-UtxoRef) | repeated | List of UTxO references to query. | -| acquire_point | [ChainPoint](#utxorpc-state-v1-ChainPoint) | | Point in the chain to query from. | - - - -## GetUtxoByRefResponse - -Response containing the UTxOs associated with the requested references. - -| Field | Type | Label | Description | -| ---------- | ---------------------------------------------- | -------- | --------------------- | -| items | [AnyChainUtxo](#utxorpc-state-v1-AnyChainUtxo) | repeated | List of UTxOs. | -| next_token | [string](#string) | | Token for pagination. | - - - -## HoldUtxoRequest - -Request to hold UTxOs. - -| Field | Type | Label | Description | -| ----- | ------------------------------------ | -------- | -------------------------------- | -| refs | [UtxoRef](#utxorpc-state-v1-UtxoRef) | repeated | List of UTxO references to hold. | - - - -## HoldUtxoResponse - -Response containing information about lost UTxOs. - -| Field | Type | Label | Description | -| ----- | ------------------------------------ | -------- | ----------------------------- | -| lost | [UtxoRef](#utxorpc-state-v1-UtxoRef) | repeated | List of lost UTxO references. | - - - -## UtxoRef - -Represents a reference to a UTxO. - -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------------- | -| hash | [bytes](#bytes) | | Transaction hash. | -| index | [uint32](#uint32) | | Output index. | - - - -## LedgerStateService - -Service definition for querying the state of the ledger. - -| Method Name | Request Type | Response Type | Description | -| ---------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------- | -| GetChainTip | [GetChainTipRequest](#utxorpc-state-v1-GetChainTipRequest) | [GetChainTipResponse](#utxorpc-state-v1-GetChainTipResponse) | Get the current chain tip. | -| GetChainParam | [GetChainParamRequest](#utxorpc-state-v1-GetChainParamRequest) | [GetChainParamResponse](#utxorpc-state-v1-GetChainParamResponse) | Get specific chain parameters. | -| GetUtxoByAddress | [GetUtxoByAddressRequest](#utxorpc-state-v1-GetUtxoByAddressRequest) | [GetUtxoByAddressResponse](#utxorpc-state-v1-GetUtxoByAddressResponse) | Get UTxOs by their associated addresses. | -| GetUtxoByRef | [GetUtxoByRefRequest](#utxorpc-state-v1-GetUtxoByRefRequest) | [GetUtxoByRefResponse](#utxorpc-state-v1-GetUtxoByRefResponse) | Get UTxOs by their references. | -| HoldUtxo | [HoldUtxoRequest](#utxorpc-state-v1-HoldUtxoRequest) | [HoldUtxoResponse](#utxorpc-state-v1-HoldUtxoResponse) stream | Hold UTxOs and receive updates about lost UTxOs | diff --git a/pages/clients.md b/pages/clients.md index c05867e..a1fb266 100644 --- a/pages/clients.md +++ b/pages/clients.md @@ -9,7 +9,7 @@ Oura is a stream processing pipeline for Cardano. It's a tool that reads data fr | Module | Status | | ------- | -------------- | | Sync | ✅ supported | -| Build | ⏺️ not required | +| Query | ⏺️ not required | | Submit | ⏺️ not required | | Watch | ⏺️ not required | | Cardano | ✅ supported | @@ -21,7 +21,7 @@ Scrolls is a data indexer for Cardano. It's a tool that reads blocks from the Ca | Module | Status | | ------- | -------------- | | Sync | ✅ supported | -| Build | ⏺️ not required | +| Query | ⏺️ not required | | Submit | ⏺️ not required | | Watch | ⏺️ not required | | Cardano | ✅ supported | diff --git a/pages/introduction.mdx b/pages/introduction.mdx index c17f96a..9611fdd 100644 --- a/pages/introduction.mdx +++ b/pages/introduction.mdx @@ -15,8 +15,8 @@ Please note that UTxO RPC is just a specification of an interface between agents The interface is divided into different modules that represent specific use-cases. Not every client will be interested in every module and not every provider will be serving every module. - - + + diff --git a/pages/query/intro.mdx b/pages/query/intro.mdx new file mode 100644 index 0000000..e9e783e --- /dev/null +++ b/pages/query/intro.mdx @@ -0,0 +1,41 @@ +import { Callout } from "nextra-theme-docs"; + +# Query Module + +The _Query_ module provides an interface for querying the state of the ledger with the main goal of constructing new transactions. + +## Operations + +- `ReadParams`: Read chain-wide parameters. +- `ReadUtxos`: Read specific UTxOs by reference. +- `SearchUtxos`: Search for UTxO based on a pattern. +- `ReadData`: Read specific data (plural of datum) by hash. + + + The schema details can be found in the [spec reference](spec). + + +## Sequence Example + +```mermaid +%%{init: { 'theme': 'dark' } }%% +sequenceDiagram + actor Client + participant QueryService + + Note over Client,QueryService: query params to define fees / other criteria + Client->>+QueryService: ReadParams (field_mask) + QueryService-->>-Client: [] + + Note over Client,QueryService: read UTxO by ref to resolve tx inputs + Client->>+QueryService: ReadUtxos (refs) + QueryService-->>-Client: ReadUtxos (utxos) + + Note over Client,QueryService: query UTxO by address to balance tx + Client->>+QueryService: SearchUtxos (address_pattern) + QueryService-->>-Client: SearchUtxos (utxos) + + Note over Client,QueryService: query UTxO by token used as beacon + Client->>+QueryService: SearchUtxos (token_pattern) + QueryService-->>-Client: SearchUtxos (utxos) +``` diff --git a/pages/query/spec.mdx b/pages/query/spec.mdx new file mode 100644 index 0000000..9e3ecf9 --- /dev/null +++ b/pages/query/spec.mdx @@ -0,0 +1,262 @@ +# Query + + + +## AnyChainDatum +An evenlope that holds a datum for any of the compatible chains + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [bytes](#bytes) | | | +| native_bytes | [bytes](#bytes) | | An opaque bytestring corresponding to native representation in the source chain. | +| cardano | [utxorpc.v1alpha.cardano.PlutusData](#utxorpc-v1alpha-cardano-PlutusData) | | A cardano UTxO | + + + + + + + + +## AnyChainParams +An evenlope that holds parameter data from any of the compatible chains + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| cardano | [utxorpc.v1alpha.cardano.PParams](#utxorpc-v1alpha-cardano-PParams) | | Cardano parameters | + + + + + + + + +## AnyUtxoData +An evenlope that holds an UTxO from any of compatible chains + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| txo_ref | [TxoRef](#utxorpc-v1alpha-query-TxoRef) | | Hash of the previous transaction. | +| native_bytes | [bytes](#bytes) | | An opaque bytestring corresponding to native representation in the source chain. | +| cardano | [utxorpc.v1alpha.cardano.TxOutput](#utxorpc-v1alpha-cardano-TxOutput) | | A cardano UTxO | + + + + + + + + +## AnyUtxoPattern +An evenlope that holds an UTxO patterns from any of compatible chains + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| cardano | [utxorpc.v1alpha.cardano.TxOutputPattern](#utxorpc-v1alpha-cardano-TxOutputPattern) | | | + + + + + + + + +## ChainPoint +Represents a specific point in the blockchain. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| slot | [uint64](#uint64) | | Slot number. | +| hash | [bytes](#bytes) | | Block hash. | + + + + + + + + +## ReadDataRequest +Request to get data (as in plural of datum) + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| keys | [bytes](#bytes) | repeated | | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields in the response. | + + + + + + + + +## ReadDataResponse +Response containing data (as in plural of datum) + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| values | [AnyChainDatum](#utxorpc-v1alpha-query-AnyChainDatum) | repeated | The value of each datum. | +| ledger_tip | [ChainPoint](#utxorpc-v1alpha-query-ChainPoint) | | The chain point that represent the ledger current position. | + + + + + + + + +## ReadParamsRequest +Request to get the chain parameters + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields in the parsed response. | + + + + + + + + +## ReadParamsResponse +Response containing the chain parameters + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| values | [AnyChainParams](#utxorpc-v1alpha-query-AnyChainParams) | | The value of the parameters. | +| ledger_tip | [ChainPoint](#utxorpc-v1alpha-query-ChainPoint) | | The chain point that represent the ledger current position. | + + + + + + + + +## ReadUtxosRequest +Request to get specific UTxOs + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| keys | [TxoRef](#utxorpc-v1alpha-query-TxoRef) | repeated | List of keys UTxOs. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | + + + + + + + + +## ReadUtxosResponse +Response containing the UTxOs associated with the requested addresses. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| items | [AnyUtxoData](#utxorpc-v1alpha-query-AnyUtxoData) | repeated | List of UTxOs. | +| ledger_tip | [ChainPoint](#utxorpc-v1alpha-query-ChainPoint) | | The chain point that represent the ledger current position. | + + + + + + + + +## SearchUtxosRequest +Reques to search for UTxO based on a pattern. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| predicate | [UtxoPredicate](#utxorpc-v1alpha-query-UtxoPredicate) | | Pattern to match UTxOs by. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | + + + + + + + + +## SearchUtxosResponse +Response containing the UTxOs that match the requested addresses. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| items | [AnyUtxoData](#utxorpc-v1alpha-query-AnyUtxoData) | repeated | List of UTxOs. | +| ledger_tip | [ChainPoint](#utxorpc-v1alpha-query-ChainPoint) | | The chain point that represent the ledger current position. | + + + + + + + + +## TxoRef +Represents a reference to a transaction output + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| hash | [bytes](#bytes) | | Tx hash. | +| index | [uint32](#uint32) | | Output index. | + + + + + + + + +## UtxoPredicate +Represents a simple utxo predicate that can composed to create more complex ones + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match | [AnyUtxoPattern](#utxorpc-v1alpha-query-AnyUtxoPattern) | | Predicate is true if tx exhibits pattern. | +| not | [UtxoPredicate](#utxorpc-v1alpha-query-UtxoPredicate) | repeated | Predicate is true if tx doesn't exhibit pattern. | +| all_of | [UtxoPredicate](#utxorpc-v1alpha-query-UtxoPredicate) | repeated | Predicate is true if utxo exhibits all of the patterns. | +| any_of | [UtxoPredicate](#utxorpc-v1alpha-query-UtxoPredicate) | repeated | Predicate is true if utxo exhibits any of the patterns. | + + + + + + + + + + + + + + +## QueryService +Service definition for querying the state of the chain. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| ReadParams | [ReadParamsRequest](#utxorpc-v1alpha-query-ReadParamsRequest) | [ReadParamsResponse](#utxorpc-v1alpha-query-ReadParamsResponse) | Get overall chain state. | +| ReadUtxos | [ReadUtxosRequest](#utxorpc-v1alpha-query-ReadUtxosRequest) | [ReadUtxosResponse](#utxorpc-v1alpha-query-ReadUtxosResponse) | Read specific UTxOs by reference. | +| SearchUtxos | [SearchUtxosRequest](#utxorpc-v1alpha-query-SearchUtxosRequest) | [SearchUtxosResponse](#utxorpc-v1alpha-query-SearchUtxosResponse) | Search for UTxO based on a pattern. | +| ReadData | [ReadDataRequest](#utxorpc-v1alpha-query-ReadDataRequest) | [ReadDataResponse](#utxorpc-v1alpha-query-ReadDataResponse) | Read specific datum by hash | + + \ No newline at end of file diff --git a/pages/servers.md b/pages/servers.md index 155e376..34798b2 100644 --- a/pages/servers.md +++ b/pages/servers.md @@ -10,7 +10,7 @@ Dolos is a Cardano "Data Node". It's a trimmed-down, Rust-based implementation o | Module | Status | | ------- | ------------- | | Sync | ✅ supported | -| Build | 🛠️ development | +| Query | 🛠️ development | | Submit | 🛠️ development | | Watch | 🛠️ development | | Cardano | ✅ supported | @@ -22,7 +22,7 @@ Blink Labs' Node API is a query layer solution for interfacing with a Cardano no | Module | Status | | ------- | ------------- | | Sync | 🛠️ development | -| Build | 🛠️ development | +| Query | 🛠️ development | | Submit | 🛠️ development | | Watch | 🛠️ development | | Cardano | 🛠️ development | @@ -34,7 +34,7 @@ Demeter is a PaaS (Platform-as-a-Service) that provides managed Cardano infrastr | Module | Status | | ------- | ------------- | | Sync | ✅ supported | -| Build | 🛠️ development | +| Query | 🛠️ development | | Submit | 🛠️ development | | Watch | 🛠️ development | | Cardano | ✅ supported | diff --git a/pages/submit/spec.mdx b/pages/submit/spec.mdx index b9df243..cb8dd1d 100644 --- a/pages/submit/spec.mdx +++ b/pages/submit/spec.mdx @@ -1,98 +1,269 @@ # Submit Module Spec - -## AnyChainTx + + +## AnyChainEval +Report containing the result of evaluating a particular transaction + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| cardano | [utxorpc.v1alpha.cardano.TxEval](#utxorpc-v1alpha-cardano-TxEval) | | A Cardano tx evaluation report. | + + + + + + + +## AnyChainTx Represents a transaction from any supported blockchain. -| Field | Type | Label | Description | -| ----- | --------------- | ----- | --------------------- | -| raw | [bytes](#bytes) | | Raw transaction data. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| raw | [bytes](#bytes) | | Raw transaction data. | + + + + + + + + +## AnyChainTxPattern +Represents a tx pattern from any supported blockchain. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| cardano | [utxorpc.v1alpha.cardano.TxPattern](#utxorpc-v1alpha-cardano-TxPattern) | | A Cardano tx pattern. | + + + + + + + + +## EvalTxRequest +Request to evaluate transactions without submitting. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tx | [AnyChainTx](#utxorpc-v1alpha-submit-AnyChainTx) | repeated | List of transactions to evaluate. | + -## CheckRequest + + + + + +## EvalTxResponse +Response containing the reports form the transaction evaluation. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| report | [AnyChainEval](#utxorpc-v1alpha-submit-AnyChainEval) | repeated | | + + + + + + + + +## ReadMempoolRequest Request to check the status of submitted transactions. -| Field | Type | Label | Description | -| ----- | --------------- | -------- | ---------------------------------------- | -| ref | [bytes](#bytes) | repeated | List of transaction references to check. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tx | [TxInMempool](#utxorpc-v1alpha-submit-TxInMempool) | repeated | List of transaction currently on the mempool. | + + -## CheckResponse + + + + +## ReadMempoolResponse Response containing the stage of the submitted transactions. -| Field | Type | Label | Description | -| ----- | --------------------------------- | -------- | ----------------------------------------------------------- | -| stage | [Stage](#utxorpc-submit-v1-Stage) | repeated | List of stages corresponding to the transaction references. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| stage | [Stage](#utxorpc-v1alpha-submit-Stage) | repeated | List of stages corresponding to the transaction references. | + + + + + -## SubmitRequest + +## SubmitTxRequest Request to submit transactions to the blockchain. -| Field | Type | Label | Description | -| ----- | ------------------------------------------- | -------- | ------------------------------- | -| tx | [AnyChainTx](#utxorpc-submit-v1-AnyChainTx) | repeated | List of transactions to submit. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tx | [AnyChainTx](#utxorpc-v1alpha-submit-AnyChainTx) | repeated | List of transactions to submit. | -## SubmitResponse + + + + + + +## SubmitTxResponse Response containing references to the submitted transactions. -| Field | Type | Label | Description | -| ----- | --------------- | -------- | ------------------------------- | -| ref | [bytes](#bytes) | repeated | List of transaction references. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ref | [bytes](#bytes) | repeated | List of transaction references. | + + -## WaitForRequest + + + + +## TxInMempool + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tx | [AnyChainTx](#utxorpc-v1alpha-submit-AnyChainTx) | | The contents of the tx | +| stage | [Stage](#utxorpc-v1alpha-submit-Stage) | | The current stage of the tx | + + + + + + + + +## TxPredicate +Represents a simple tx predicate that can composed to create more complex ones + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match | [AnyChainTxPattern](#utxorpc-v1alpha-submit-AnyChainTxPattern) | | Predicate is true if tx exhibits pattern. | +| not | [TxPredicate](#utxorpc-v1alpha-submit-TxPredicate) | repeated | Predicate is true if tx doesn't exhibit pattern. | +| all_of | [TxPredicate](#utxorpc-v1alpha-submit-TxPredicate) | repeated | Predicate is true if tx exhibits all of the patterns. | +| any_of | [TxPredicate](#utxorpc-v1alpha-submit-TxPredicate) | repeated | Predicate is true if tx exhibits any of the patterns. | + + + + + + + + +## WaitForTxRequest Request to wait for transactions to reach a certain stage. -| Field | Type | Label | Description | -| ----- | --------------- | -------- | ------------------------------------------- | -| ref | [bytes](#bytes) | repeated | List of transaction references to wait for. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ref | [bytes](#bytes) | repeated | List of transaction references to wait for. | + -## WaitForResponse + + + + + +## WaitForTxResponse Response containing the transaction reference and stage once it has been reached. -| Field | Type | Label | Description | -| ----- | --------------------------------- | ----- | --------------------------------- | -| ref | [bytes](#bytes) | | Transaction reference. | -| stage | [Stage](#utxorpc-submit-v1-Stage) | | Stage reached by the transaction. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ref | [bytes](#bytes) | | Transaction reference. | +| stage | [Stage](#utxorpc-v1alpha-submit-Stage) | | Stage reached by the transaction. | + + -## Stage + + + + +## WatchMempoolRequest +Request to watch changes of specific mempool txs. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| predicate | [TxPredicate](#utxorpc-v1alpha-submit-TxPredicate) | | A predicate to filter transactions by. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | + + + + + + + + +## WatchMempoolResponse +Response that represents a change in a mempool tx. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tx | [TxInMempool](#utxorpc-v1alpha-submit-TxInMempool) | | The content and stage of the tx that has changed | + + + + + + + + + + +## Stage Enum representing the various stages of a transaction's lifecycle. -| Name | Number | Description | -| ------------------ | ------ | --------------------------------------------------- | -| STAGE_UNSPECIFIED | 0 | Unspecified stage. | -| STAGE_ACKNOWLEDGED | 1 | Transaction has been acknowledged by the node. | -| STAGE_MEMPOOL | 2 | Transaction is in the mempool. | -| STAGE_NETWORK | 3 | Transaction has been propagated across the network. | -| STAGE_CONFIRMED | 4 | Transaction has been confirmed on the blockchain. | +| Name | Number | Description | +| ---- | ------ | ----------- | +| STAGE_UNSPECIFIED | 0 | Unspecified stage. | +| STAGE_ACKNOWLEDGED | 1 | Transaction has been acknowledged by the node. | +| STAGE_MEMPOOL | 2 | Transaction is in the mempool. | +| STAGE_NETWORK | 3 | Transaction has been propagated across the network. | +| STAGE_CONFIRMED | 4 | Transaction has been confirmed on the blockchain. | - -## SubmitService + + + + + + +## SubmitService Service definition for submitting transactions and checking their status. -| Method Name | Request Type | Response Type | Description | -| ----------- | --------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- | -| Submit | [SubmitRequest](#utxorpc-submit-v1-SubmitRequest) | [SubmitResponse](#utxorpc-submit-v1-SubmitResponse) | Submit transactions to the blockchain. | -| Check | [CheckRequest](#utxorpc-submit-v1-CheckRequest) | [CheckResponse](#utxorpc-submit-v1-CheckResponse) | Check the status of submitted transactions. | -| WaitFor | [WaitForRequest](#utxorpc-submit-v1-WaitForRequest) | [WaitForResponse](#utxorpc-submit-v1-WaitForResponse) stream | Wait for transactions to reach a certain stage and stream the updates. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| EvalTx | [EvalTxRequest](#utxorpc-v1alpha-submit-EvalTxRequest) | [EvalTxResponse](#utxorpc-v1alpha-submit-EvalTxResponse) | Evaluates a transaction without submitting it. | +| SubmitTx | [SubmitTxRequest](#utxorpc-v1alpha-submit-SubmitTxRequest) | [SubmitTxResponse](#utxorpc-v1alpha-submit-SubmitTxResponse) | Submit transactions to the blockchain. | +| WaitForTx | [WaitForTxRequest](#utxorpc-v1alpha-submit-WaitForTxRequest) | [WaitForTxResponse](#utxorpc-v1alpha-submit-WaitForTxResponse) stream | Wait for transactions to reach a certain stage and stream the updates. | +| ReadMempool | [ReadMempoolRequest](#utxorpc-v1alpha-submit-ReadMempoolRequest) | [ReadMempoolResponse](#utxorpc-v1alpha-submit-ReadMempoolResponse) | Returns a point-in-time snapshot of the mempool. | +| WatchMempool | [WatchMempoolRequest](#utxorpc-v1alpha-submit-WatchMempoolRequest) | [WatchMempoolResponse](#utxorpc-v1alpha-submit-WatchMempoolResponse) stream | Stream transactions from the mempool matching the specified predicates. | + + diff --git a/pages/sync/spec.mdx b/pages/sync/spec.mdx index 902b706..0c74793 100644 --- a/pages/sync/spec.mdx +++ b/pages/sync/spec.mdx @@ -1,133 +1,150 @@ # Sync Module - -## AnyChainTx + -| Field | Type | Label | Description | -| ------- | ----------------------------------------------- | ----- | ---------------------- | -| cardano | [utxorpc.cardano.v1.Tx](#utxorpc-cardano-v1-Tx) | | A Cardano transaction. | +## AnyChainBlock - -## Block -Represents a complete block, including header and body. +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| raw | [bytes](#bytes) | | Original bytes for a raw block | +| cardano | [utxorpc.v1alpha.cardano.Block](#utxorpc-v1alpha-cardano-Block) | | A parsed Cardano block. | -| Field | Type | Label | Description | -| ------ | ------------------------------------------- | ----- | ------------------------ | -| header | [BlockHeader](#utxorpc-sync-v1-BlockHeader) | | Block header. | -| body | [BlockBody](#utxorpc-sync-v1-BlockBody) | | Block body. | -| cbor | [bytes](#bytes) | | CBOR-encoded block data. | - -## BlockBody -Contains the transaction data for a block. -| Field | Type | Label | Description | -| ----- | ----------------------------------------- | -------- | --------------------- | -| tx | [AnyChainTx](#utxorpc-sync-v1-AnyChainTx) | repeated | List of transactions. | - + -## BlockHeader +## BlockRef +Represents a reference to a specific block -Contains the header information for a block. -| Field | Type | Label | Description | -| ------ | ----------------- | ----- | ------------- | -| slot | [uint64](#uint64) | | Slot number. | -| height | [uint64](#uint64) | | Block height. | -| hash | [string](#string) | | Block hash. | +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| index | [uint64](#uint64) | | Height or slot number (depending on the blockchain) | +| hash | [bytes](#bytes) | | Hash of the content of the block | - -## BlockRef -Represents a reference to a specific block. -| Field | Type | Label | Description | -| ------ | ----------------- | ----- | ------------- | -| slot | [uint64](#uint64) | | Slot number. | -| height | [uint64](#uint64) | | Block height. | -| hash | [string](#string) | | Block hash. | - -## DumpHistoryRequest + +## DumpHistoryRequest Request to dump the block history. -| Field | Type | Label | Description | -| ----------- | ------------------------------------------------------- | ----- | ------------------------------------------ | -| start_token | [BlockRef](#utxorpc-sync-v1-BlockRef) | | Starting point for the block history dump. | -| max_items | [uint32](#uint32) | | Maximum number of items to return. | -| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| start_token | [BlockRef](#utxorpc-v1alpha-sync-BlockRef) | | Starting point for the block history dump. | +| max_items | [uint32](#uint32) | | Maximum number of items to return. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | + -## DumpHistoryResponse + + + + + +## DumpHistoryResponse Response containing the dumped block history. -| Field | Type | Label | Description | -| ---------- | ------------------------------------- | -------- | ------------------------------ | -| block | [Block](#utxorpc-sync-v1-Block) | repeated | List of blocks in the history. | -| next_token | [BlockRef](#utxorpc-sync-v1-BlockRef) | | Next token for pagination. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| block | [AnyChainBlock](#utxorpc-v1alpha-sync-AnyChainBlock) | repeated | List of blocks in the history. | +| next_token | [BlockRef](#utxorpc-v1alpha-sync-BlockRef) | | Next token for pagination. | -## FetchBlockRequest + + + + + + +## FetchBlockRequest Request to fetch a block by its reference. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------------------- | -------- | ---------------------------------------- | -| ref | [BlockRef](#utxorpc-sync-v1-BlockRef) | repeated | List of block references. | -| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ref | [BlockRef](#utxorpc-v1alpha-sync-BlockRef) | repeated | List of block references. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | -## FetchBlockResponse + + + + + + +## FetchBlockResponse Response containing the fetched blocks. -| Field | Type | Label | Description | -| ----- | ------------------------------- | -------- | ----------------------- | -| block | [Block](#utxorpc-sync-v1-Block) | repeated | List of fetched blocks. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| block | [AnyChainBlock](#utxorpc-v1alpha-sync-AnyChainBlock) | repeated | List of fetched blocks. | + + + + -## FollowTipRequest + + +## FollowTipRequest Request to follow the tip of the blockchain. -| Field | Type | Label | Description | -| --------- | ------------------------------------- | -------- | -------------------------------------------------- | -| intersect | [BlockRef](#utxorpc-sync-v1-BlockRef) | repeated | List of block references to find the intersection. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| intersect | [BlockRef](#utxorpc-v1alpha-sync-BlockRef) | repeated | List of block references to find the intersection. | +| field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | + + + -## FollowTipResponse + + + +## FollowTipResponse Response containing the action to perform while following the tip. -| Field | Type | Label | Description | -| ----- | ------------------------------------- | ----- | ------------------------------ | -| apply | [Block](#utxorpc-sync-v1-Block) | | Apply this block. | -| undo | [Block](#utxorpc-sync-v1-Block) | | Undo this block. | -| reset | [BlockRef](#utxorpc-sync-v1-BlockRef) | | Reset to this block reference. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| apply | [AnyChainBlock](#utxorpc-v1alpha-sync-AnyChainBlock) | | Apply this block. | +| undo | [AnyChainBlock](#utxorpc-v1alpha-sync-AnyChainBlock) | | Undo this block. | +| reset | [BlockRef](#utxorpc-v1alpha-sync-BlockRef) | | Reset to this block reference. | + + + -## ChainSyncService + + + + + + + + + +## SyncService Service definition for syncing chain data. -| Method Name | Request Type | Response Type | Description | -| ----------- | --------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------- | -| FetchBlock | [FetchBlockRequest](#utxorpc-sync-v1-FetchBlockRequest) | [FetchBlockResponse](#utxorpc-sync-v1-FetchBlockResponse) | Fetch a block by its reference. | -| DumpHistory | [DumpHistoryRequest](#utxorpc-sync-v1-DumpHistoryRequest) | [DumpHistoryResponse](#utxorpc-sync-v1-DumpHistoryResponse) | Dump the block history. | -| FollowTip | [FollowTipRequest](#utxorpc-sync-v1-FollowTipRequest) | [FollowTipResponse](#utxorpc-sync-v1-FollowTipResponse) stream | Follow the tip of the blockchain. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| FetchBlock | [FetchBlockRequest](#utxorpc-v1alpha-sync-FetchBlockRequest) | [FetchBlockResponse](#utxorpc-v1alpha-sync-FetchBlockResponse) | Fetch a block by its reference. | +| DumpHistory | [DumpHistoryRequest](#utxorpc-v1alpha-sync-DumpHistoryRequest) | [DumpHistoryResponse](#utxorpc-v1alpha-sync-DumpHistoryResponse) | Dump the block history. | +| FollowTip | [FollowTipRequest](#utxorpc-v1alpha-sync-FollowTipRequest) | [FollowTipResponse](#utxorpc-v1alpha-sync-FollowTipResponse) stream | Follow the tip of the blockchain. | + + diff --git a/pages/watch/spec.mdx b/pages/watch/spec.mdx index 5cfe4b7..b33159a 100644 --- a/pages/watch/spec.mdx +++ b/pages/watch/spec.mdx @@ -1,23 +1,7 @@ # Watch Module - -## AddressPredicate -Predicate to match transactions based on addresses. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| match_source | [bytes](#bytes) | | Match transactions with the specified source address. | -| match_target | [bytes](#bytes) | | Match transactions with the specified target address. | -| match_any | [bytes](#bytes) | | Match transactions with the specified address as either source or target. | - - - - - - - + ## AnyChainTx Represents a transaction from any supported blockchain. @@ -25,104 +9,89 @@ Represents a transaction from any supported blockchain. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| cardano | [utxorpc.cardano.v1.Tx](#utxorpc-cardano-v1-Tx) | | A Cardano transaction. | - - - - - - - - -## AnyPredicate -Predicate to match transactions based on any of the specified types. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| address | [AddressPredicate](#utxorpc-watch-v1-AddressPredicate) | | Address-based predicate. | -| asset | [AssetPredicate](#utxorpc-watch-v1-AssetPredicate) | | Asset-based predicate. | -| utxo | [UtxoPredicate](#utxorpc-watch-v1-UtxoPredicate) | | UTXO-based predicate. | -| datum | [DatumPredicate](#utxorpc-watch-v1-DatumPredicate) | | Datum-based predicate. | +| cardano | [utxorpc.v1alpha.cardano.Tx](#utxorpc-v1alpha-cardano-Tx) | | A Cardano transaction. | - + -## AssetPredicate -Predicate to match transactions based on assets. +## AnyChainTxPattern +Represents a tx pattern from any supported blockchain. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| match_policy | [bytes](#bytes) | | Match transactions with the specified asset policy. | -| match_name | [bytes](#bytes) | | Match transactions with the specified asset name. | +| cardano | [utxorpc.v1alpha.cardano.TxPattern](#utxorpc-v1alpha-cardano-TxPattern) | | A Cardano tx pattern. | - + -## DatumPredicate -Predicate to match transactions based on datums. +## BlockRef +Represents a reference to a specific block | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| match_hash | [bytes](#bytes) | | Match transactions with the specified datum hash. | +| index | [uint64](#uint64) | | Height or slot number (depending on the blockchain) | +| hash | [bytes](#bytes) | | Hash of the content of the block | - + -## UtxoPredicate -Predicate to match transactions based on UTXOs. +## TxPredicate +Represents a simple tx predicate that can composed to create more complex ones | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| match_hash | [bytes](#bytes) | | Match transactions with the specified UTXO hash. | -| match_index | [uint32](#uint32) | | Match transactions with the specified UTXO index. | +| match | [AnyChainTxPattern](#utxorpc-v1alpha-watch-AnyChainTxPattern) | | Predicate is true if tx exhibits pattern. | +| not | [TxPredicate](#utxorpc-v1alpha-watch-TxPredicate) | repeated | Predicate is true if tx doesn't exhibit pattern. | +| all_of | [TxPredicate](#utxorpc-v1alpha-watch-TxPredicate) | repeated | Predicate is true if tx exhibits all of the patterns. | +| any_of | [TxPredicate](#utxorpc-v1alpha-watch-TxPredicate) | repeated | Predicate is true if tx exhibits any of the patterns. | - + ## WatchTxRequest -Request to watch transactions based on a set of predicates. +Request to watch transactions from the chain based on a set of predicates. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| predicate | [AnyPredicate](#utxorpc-watch-v1-AnyPredicate) | repeated | List of predicates to filter transactions. | +| predicate | [TxPredicate](#utxorpc-v1alpha-watch-TxPredicate) | | Predicate to filter transactions by. | | field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) | | Field mask to selectively return fields. | +| intersect | [BlockRef](#utxorpc-v1alpha-watch-BlockRef) | repeated | List of block references to find the intersection. | - + ## WatchTxResponse -Response containing the matching transactions. +Response containing the matching chain transactions. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| apply | [AnyChainTx](#utxorpc-watch-v1-AnyChainTx) | | Apply this transaction. | -| undo | [AnyChainTx](#utxorpc-watch-v1-AnyChainTx) | | Undo this transaction. | +| apply | [AnyChainTx](#utxorpc-v1alpha-watch-AnyChainTx) | | Apply this transaction. | +| undo | [AnyChainTx](#utxorpc-v1alpha-watch-AnyChainTx) | | Undo this transaction. | @@ -135,13 +104,13 @@ Response containing the matching transactions. - + -## TxWatchService +## WatchService Service definition for watching transactions based on predicates. | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| -| WatchTx | [WatchTxRequest](#utxorpc-watch-v1-WatchTxRequest) | [WatchTxResponse](#utxorpc-watch-v1-WatchTxResponse) stream | Stream transactions matching the specified predicates. | +| WatchTx | [WatchTxRequest](#utxorpc-v1alpha-watch-WatchTxRequest) | [WatchTxResponse](#utxorpc-v1alpha-watch-WatchTxResponse) stream | Stream transactions from the chain matching the specified predicates. | - \ No newline at end of file +