From ae45314b0a3416a340574f588213e735fdc6a41e Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Tue, 4 Jun 2024 19:43:02 +0400 Subject: [PATCH 1/4] Add a rough draft --- CIP-XXXX/README.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 CIP-XXXX/README.md diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md new file mode 100644 index 0000000000..929a3beeca --- /dev/null +++ b/CIP-XXXX/README.md @@ -0,0 +1,90 @@ +--- +CIP: +Title: Universal Query Layer +Category: Tools +Status: Proposed +Authors: + - Vladimir Kalnitsky +Implementors: [] +Discussions: + - https://discord.gg/MU8vHAgmGy +Created: 2024-05-14 +License: CC-BY-4.0 +--- + +## Abstract + + +A transport-agnostic query layer specification for use in dApps and wallets. + +## Motivation: why is this CIP necessary? + +See [CPS-12](https://github.com/cardano-foundation/CIPs/pull/625) for motivation. + +## Specification + + + +### Design principles + +There are two approaches to Cardano dApp development: + +1. **Using customized chain followers**. A chain follower is a program that interacts with cardano-node and processes all incoming transactions, as well as rollbacks, to maintain consistent dApp-specific state. Example: [Carp](https://dcspark.github.io/carp/docs/intro/). + +2. **Using general-purpose query layers**. General-purpose query layers allow to query blockchain data using a wide set of APIs that are not built with a particular dApp domain in mind. dApp state has to be constructed based on data returned from the queries. + +The first approach allows for lower runtime resource consumption, but a general-purpose query layer has an advantage of being more easily reusable between dApps. + +In this proposal, we are focusing on general-purpose querying only. + +#### Handling of rollbacks + +Transaction rollbacks are essential to blockchains: local node's view of the chain may be different from other nodes'. During conflict resolution, the node may issue a rollback event, that must be handled by dApps. + +Rollback handling + +#### Error handling + +Errors should be divided in two categories: + +- domain errors +- transport errors (404, 500, etc) + +This document should only cover domain errors. + +### Methods + +#### `get_address_utxos` + +- `address` +- `slot` + +#### `get_transaction` + +#### `get_script_by_hash` + +#### `get_datum_by_hash` + +## Rationale: how does this CIP achieve its goals? + + +## Path to Active + +### Acceptance Criteria + + + + +### Implementation Plan + + + + +## Copyright + + + + From c0ad4cf3bd71d770395c636e33483df7ff3b43cf Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 1 Aug 2024 18:04:01 +0400 Subject: [PATCH 2/4] WIP: a draft for the query layers CIP --- CIP-XXXX/Query_Layer_API_Comparison.md | 139 ++++++++++++++++ CIP-XXXX/README.md | 219 +++++++++++++++++++++++-- 2 files changed, 346 insertions(+), 12 deletions(-) create mode 100644 CIP-XXXX/Query_Layer_API_Comparison.md diff --git a/CIP-XXXX/Query_Layer_API_Comparison.md b/CIP-XXXX/Query_Layer_API_Comparison.md new file mode 100644 index 0000000000..5f6635fe65 --- /dev/null +++ b/CIP-XXXX/Query_Layer_API_Comparison.md @@ -0,0 +1,139 @@ +# WIP Query Layer API Comparison (1) + +| | Blockfrost | Maestro | Koios | +|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------| +| Accounts | | | | +| List of all stake addresses | | | https://api.koios.rest/#get-/account_list | +| Account info | https://blockfrost.dev/api/specific-account-address | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-info | https://api.koios.rest/#post-/account_info | +| Account reward history | https://blockfrost.dev/api/account-reward-history | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-rewards | https://api.koios.rest/#post-/account_rewards | +| Account history | https://blockfrost.dev/api/account-history | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-history | https://api.koios.rest/#post-/account_history | +| Account delegation history | https://blockfrost.dev/api/account-delegation-history | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-delegations | https://api.koios.rest/#post-/account_updates | +| Account registration history | https://blockfrost.dev/api/account-registration-history | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-updates | https://api.koios.rest/#post-/account_updates | +| Account withdrawal history | https://blockfrost.dev/api/account-withdrawal-history | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-updates | https://api.koios.rest/#post-/account_updates | +| Account MIR history | https://blockfrost.dev/api/account-mir-history | | https://api.koios.rest/#post-/account_rewards | +| Account associated addresses | https://blockfrost.dev/api/account-associated-addresses | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-addresses | https://api.koios.rest/#post-/account_addresses | +| Assets associated with the account addresses | https://blockfrost.dev/api/assets-associated-with-the-account-addresses | https://docs.gomaestro.org/Cardano/Indexer-API/Accounts/account-assets | https://api.koios.rest/#post-/account_assets | +| Summed details of account addresses | https://blockfrost.dev/api/detailed-information-about-account-associated-addresses | | | +| Account utxos | | | https://api.koios.rest/#post-/account_utxos | +| Addresses | | | | +| Address details/balance | https://blockfrost.dev/api/specific-address | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/balance-by-payment-cred | https://api.koios.rest/#post-/address_info | +| Extended information of an address / assets | https://blockfrost.dev/api/extended-information-of-a-specific-address | | https://api.koios.rest/#post-/address_assets | +| Address details / tx count | https://blockfrost.dev/api/address-details | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/tx-count-by-address | | +| Address UTXOs | https://blockfrost.dev/api/address-utx-os | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/utxos-by-address | https://api.koios.rest/#post-/address_utxos | +| Address UTXOs of a given asset | https://blockfrost.dev/api/address-utx-os-of-a-given-asset | | | +| UTxO references at an address | | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/utxo-refs-at-address | | +| UTxOs by multiple addresses | | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/utxos-by-addresses | | +| UTxOs by payment credential(s) | | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/utxos-by-payment-cred | | +| Address transactions | https://blockfrost.dev/api/address-transactions | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/txs-by-address | https://api.koios.rest/#post-/address_txs | +| Payment credential(s) transactions | | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/txs-by-payment-cred | | +| Decode address | | https://docs.gomaestro.org/Cardano/Indexer-API/Addresses/decode-address | | +| Assets | | | | +| List of all assets | https://blockfrost.dev/api/assets | | https://api.koios.rest/#get-/asset_list | +| List of assets registered via token registry | | | https://api.koios.rest/#get-/asset_token_registry | +| Asset info | https://blockfrost.dev/api/specific-asset | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-info | https://api.koios.rest/#post-/asset_info | +| Asset mint/burn history | https://blockfrost.dev/api/asset-history | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-mints | https://api.koios.rest/#get-/asset_history | +| Asset transactions | https://blockfrost.dev/api/asset-transactions | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-txs | https://api.koios.rest/#get-/asset_txs | +| Asset addresses | https://blockfrost.dev/api/asset-addresses | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-addresses | https://api.koios.rest/#get-/asset_addresses | +| Asset summary | | | https://api.koios.rest/#get-/asset_summary | +| NFT address | | | https://api.koios.rest/#get-/asset_nft_address | +| Asset accounts | | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-accounts | | +| Asset UTxOs | | https://docs.gomaestro.org/Cardano/Indexer-API/Assets/asset-utxos | https://api.koios.rest/#post-/asset_utxos | +| Assets of a specific policy | https://blockfrost.dev/api/assets-of-a-specific-policy | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-assets | https://api.koios.rest/#get-/policy_asset_list | +| Policy assets information | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-info | https://api.koios.rest/#get-/policy_asset_info | +| Policy accounts | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-accounts | | +| Policy addresses | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-addresses | https://api.koios.rest/#get-/policy_asset_addresses | +| Policy mint/burn history | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-mints | https://api.koios.rest/#get-/policy_asset_mints | +| Policy tx history | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-txs | | +| Policy UTxOs | | https://docs.gomaestro.org/Cardano/Indexer-API/Asset%20Policy/policy-utxos | | +| Blocks | | | | +| List of all blocks | | | https://api.koios.rest/#get-/blocks | +| Latest block info | https://blockfrost.dev/api/latest-block | https://docs.gomaestro.org/Cardano/Indexer-API/Blocks/latest-block | | +| Latest block transactions | https://blockfrost.dev/api/latest-block-transactions | | | +| Block info | https://blockfrost.dev/api/specific-block | https://docs.gomaestro.org/Cardano/Indexer-API/Blocks/block-info | https://api.koios.rest/#post-/block_info | +| Listing of next blocks | https://blockfrost.dev/api/listing-of-next-blocks | | | +| Listing of previous blocks | https://blockfrost.dev/api/listing-of-previous-blocks | | | +| Specific block in a slot | https://blockfrost.dev/api/specific-block-in-a-slot | | | +| Specific block in a slot in an epoch | https://blockfrost.dev/api/specific-block-in-a-slot-in-an-epoch | | | +| Block transactions | https://blockfrost.dev/api/block-transactions | | https://api.koios.rest/#post-/block_txs | +| Addresses affected in a specific block | https://blockfrost.dev/api/addresses-affected-in-a-specific-block | | | +| Epochs | | | | +| Latest epoch | https://blockfrost.dev/api/latest-epoch | https://docs.gomaestro.org/Cardano/Indexer-API/Epochs/current-epoch | | +| Latest epoch protocol parameters | https://blockfrost.dev/api/latest-epoch-protocol-parameters | | | +| Specific epoch | https://blockfrost.dev/api/specific-epoch | https://docs.gomaestro.org/Cardano/Indexer-API/Epochs/epoch-info | https://api.koios.rest/#get-/epoch_info | +| Listing of next epochs | https://blockfrost.dev/api/listing-of-next-epochs | | | +| Listing of previous epochs | https://blockfrost.dev/api/listing-of-previous-epochs | | | +| Stake distribution | https://blockfrost.dev/api/stake-distribution | | | +| Stake distribution by pool | https://blockfrost.dev/api/stake-distribution-by-pool | | | +| Block distribution | https://blockfrost.dev/api/block-distribution | | | +| Block distribution by pool | https://blockfrost.dev/api/block-distribution-by-pool | | | +| Block protocols | | | https://api.koios.rest/#get-/epoch_block_protocols | +| Protocol parameters by epoch | https://blockfrost.dev/api/protocol-parameters | | https://api.koios.rest/#get-/epoch_params | +| Current protocol parameters | | https://docs.gomaestro.org/Cardano/Indexer-API/General/protocol-parameters | https://api.koios.rest/#get-/cli_protocol_params | +| General | | | | +| Blockchain genesis | https://blockfrost.dev/api/blockchain-genesis | | https://api.koios.rest/#get-/genesis | +| Blockchain system start | | https://docs.gomaestro.org/Cardano/Indexer-API/General/system-start | | +| Chain tip | | https://docs.gomaestro.org/Cardano/Indexer-API/General/chain-tip | | +| Mempool | | | | +| Mempool transactions | https://blockfrost.dev/api/mempool | | | +| Specific transaction in the mempool | https://blockfrost.dev/api/specific-transaction-in-the-mempool | | | +| Mempool by address | https://blockfrost.dev/api/mempool-by-address | | | +| Metadata | | | | +| Transaction metadata labels | https://blockfrost.dev/api/transaction-metadata-labels | | | +| Transaction metadata content in JSON | https://blockfrost.dev/api/transaction-metadata-content-in-json | | | +| Transaction metadata content in CBOR | https://blockfrost.dev/api/transaction-metadata-content-in-cbor | | | +| Network | | | | +| Network information | https://blockfrost.dev/api/network-information | | https://api.koios.rest/#get-/tip | +| Query summary of blockchain eras | https://blockfrost.dev/api/query-summary-of-blockchain-eras | https://docs.gomaestro.org/Cardano/Indexer-API/General/era-summaries | | +| Historical tokenomic stats | | | https://api.koios.rest/#get-/totals | +| Param update proposals | | | https://api.koios.rest/#get-/param_updates | +| Reserve withdrawals | | | https://api.koios.rest/#get-/reserve_withdrawals | +| Treasury withdrawals | | | https://api.koios.rest/#get-/treasury_withdrawals | +| Pools | | | | +| List of stake pools | https://blockfrost.dev/api/list-of-stake-pools | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/list-pools | https://api.koios.rest/#get-/pool_list | +| List of stake pools with additional information | https://blockfrost.dev/api/list-of-stake-pools-with-additional-information | | | +| List of retired stake pools | https://blockfrost.dev/api/list-of-retired-stake-pools | | | +| List of retiring stake pools | https://blockfrost.dev/api/list-of-retiring-stake-pools | | | +| List of stake pool retirements | | | https://api.koios.rest/#get-/pool_retirements | +| Stake pool info | https://blockfrost.dev/api/specific-stake-pool | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-info | https://api.koios.rest/#post-/pool_info | +| Stake pool history | https://blockfrost.dev/api/stake-pool-history | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-history | https://api.koios.rest/#get-/pool_history | +| Stake pool metadata | https://blockfrost.dev/api/stake-pool-metadata | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-metadata | https://api.koios.rest/#post-/pool_metadata | +| Stake pool relays | https://blockfrost.dev/api/stake-pool-relays | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-relays | https://api.koios.rest/#get-/pool_relays | +| Stake pool delegators | https://blockfrost.dev/api/stake-pool-delegators | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-delegators | https://api.koios.rest/#get-/pool_delegators | +| Stake pool delegator history | | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-historical-delegators | https://api.koios.rest/#get-/pool_delegators_history | +| Stake pool blocks | https://blockfrost.dev/api/stake-pool-blocks | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-blocks | https://api.koios.rest/#get-/pool_blocks | +| Stake pool updates | https://blockfrost.dev/api/stake-pool-updates | https://docs.gomaestro.org/Cardano/Indexer-API/Pools/pool-updates | https://api.koios.rest/#get-/pool_updates | +| Stake pool stake snapshot | | | https://api.koios.rest/#get-/pool_stake_snapshot | +| Stake pool registrations | | | https://api.koios.rest/#get-/pool_registrations | +| Scripts | | | | +| List of scripts | https://blockfrost.dev/api/scripts | | https://api.koios.rest/#get-/native_script_list | +| Script info | https://blockfrost.dev/api/specific-script | https://docs.gomaestro.org/Cardano/Indexer-API/Scripts/script-by-hash | https://api.koios.rest/#post-/script_info | +| Script JSON | https://blockfrost.dev/api/script-json | | | +| Script CBOR | https://blockfrost.dev/api/script-cbor | | | +| Redeemers of a specific script | https://blockfrost.dev/api/redeemers-of-a-specific-script | | https://api.koios.rest/#get-/script_redeemers | +| Script UTxOs | | | https://api.koios.rest/#get-/script_utxos | +| Datums | | | | +| Datum value | https://blockfrost.dev/api/datum-value | https://docs.gomaestro.org/Cardano/Indexer-API/Datum/datum-by-hash | | +| Datum CBOR value | https://blockfrost.dev/api/datum-cbor-value | | https://api.koios.rest/#post-/datum_info | +| Transactions | | | | +| Transaction info | https://blockfrost.dev/api/specific-transaction | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/tx-info | https://api.koios.rest/#post-/tx_info | +| Transaction UTXOs | https://blockfrost.dev/api/transaction-utx-os | | https://api.koios.rest/#post-/utxo_info | +| Transaction output by output ref | | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/txo-by-txo-ref | | +| Transaction outputs by output refs | | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/txos-by-txo-refs | | +| Transaction address by output ref | | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/address-by-txo | | +| Transaction stake addresses certificates | https://blockfrost.dev/api/transaction-stake-addresses-certificates | | | +| Transaction delegation certificates | https://blockfrost.dev/api/transaction-delegation-certificates | | | +| Transaction withdrawal | https://blockfrost.dev/api/transaction-withdrawal | | | +| Transaction MIRs | https://blockfrost.dev/api/transaction-mi-rs | | | +| Transaction stake pool registration and update certificates | https://blockfrost.dev/api/transaction-stake-pool-registration-and-update-certificates | | | +| Transaction stake pool retirement certificates | https://blockfrost.dev/api/transaction-stake-pool-retirement-certificates | | | +| Transaction CBOR | | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/tx-cbor-by-tx-hash | | +| Transaction metadata | https://blockfrost.dev/api/transaction-metadata | | https://api.koios.rest/#post-/tx_metadata | +| Transaction metadata labels | | | https://api.koios.rest/#get-/tx_metalabels | +| Transaction metadata in CBOR | https://blockfrost.dev/api/transaction-metadata-in-cbor | | | +| Transaction redeemers | https://blockfrost.dev/api/transaction-redeemers | | | +| Submit a transaction | https://blockfrost.dev/api/submit-a-transaction | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/iog-tx-submit | https://api.koios.rest/#post-/submittx | +| Transaction confirmations | | | https://api.koios.rest/#post-/tx_status | +| Utilities | | | | +| Derive an address | https://blockfrost.dev/api/derive-an-address | | | +| Submit a transaction for execution units evaluation | https://blockfrost.dev/api/submit-a-transaction-for-execution-units-evaluation | https://docs.gomaestro.org/Cardano/Indexer-API/Transactions/evaluate-redeemers | | +| Submit a transaction for execution units evaluation (additional UTXO set) | https://blockfrost.dev/api/submit-a-transaction-for-execution-units-evaluation-additional-utxo-set | | | diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 929a3beeca..8ee815f479 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -25,13 +25,13 @@ See [CPS-12](https://github.com/cardano-foundation/CIPs/pull/625) for motivation -### Design principles +### Existing Query Layer designs There are two approaches to Cardano dApp development: 1. **Using customized chain followers**. A chain follower is a program that interacts with cardano-node and processes all incoming transactions, as well as rollbacks, to maintain consistent dApp-specific state. Example: [Carp](https://dcspark.github.io/carp/docs/intro/). -2. **Using general-purpose query layers**. General-purpose query layers allow to query blockchain data using a wide set of APIs that are not built with a particular dApp domain in mind. dApp state has to be constructed based on data returned from the queries. +2. **Using general-purpose query layers**. General-purpose query layers allow to query blockchain data using a wide set of APIs that are not built with a particular dApp domain in mind. dApp state has to be constructed based on data returned from the queries. Examples: Blockfrost, Maestro. The first approach allows for lower runtime resource consumption, but a general-purpose query layer has an advantage of being more easily reusable between dApps. @@ -39,9 +39,11 @@ In this proposal, we are focusing on general-purpose querying only. #### Handling of rollbacks -Transaction rollbacks are essential to blockchains: local node's view of the chain may be different from other nodes'. During conflict resolution, the node may issue a rollback event, that must be handled by dApps. +Transaction rollbacks are essential to blockchains: local node's view of the chain may be different from other nodes'. During conflict resolution, the node may issue a rollback event, that should be handled by dApps. -Rollback handling +Customized chain followers, at least in principle, allow for "live" rollback handling: that is, a user-facing dApp can subscribe to a local view of a part of the UTxO set. + +General purpose query layers can also handle rollbacks just fine, but they don't propagate rollback events to dApps, because they do not possess any dApp-specific info to determine if a dApp *needs* to handle a particular rollback. dApps that work with general-purpose query layers follow pull-based architecture, rather than event subscription-based, which means they just request data as needed, instead of reacting to blockchain events. #### Error handling @@ -54,18 +56,207 @@ This document should only cover domain errors. ### Methods -#### `get_address_utxos` +This section contains transport-agnostic method descriptions & their parameter lists. + +The scope of this section is loosely based on a [comparison table for existing Cardano query layers](./Query_Layer_API_Comparison.md). +The goal is to make it so that the API could be implemented via simple adapters that transform requests and responses to the appropriate formats. + +The payload formats used below are references to [CIP-0116 - Standard JSON encoding for Domain Types](https://cips.cardano.org/cip/CIP-0116), which specifies cardano domain types via a JSON schema. + +#### UTxOs + +##### By address + +Request: + +- address: `Address` +- slot?: `UInt64` + +Response: + +- `TransactionUnspentOutput[]` + +##### By payment credential + +Request: + +- credential: `Credential` +- slot?: `UInt64` + +Response: + +- `TransactionUnspentOutput[]` + +##### By staking credential + +Request: + +- credential: `Credential` +- slot?: `UInt64` + +Response: + +- `TransactionUnspentOutput[]` + +##### By asset + +Request: + +- script_hash: `ScriptHash` +- asset_name: `AssetName` +- slot?: `UInt64` + +Response: + +- `TransactionUnspentOutput[]` + +##### By transaction ID + +- transaction_hash: `TransactionHash` +- slot?: `UInt64` + +Response: + +- `TransactionUnspentOutput[]` + +#### Transaction + +TODO: decide if we want mempool transactions, want to forbid these, or it doesn't matter. + +##### By hash + +Request: + +- transaction_hash: `TransactionHash` + +Response: + +- `Transaction` + +#### Script + +##### Native Script by hash + +Request: + +- `ScriptHash` + +Response: + +- `NativeScript` + +##### Plutus Script by hash + +Request: + +- `ScriptHash` + +Response: + +- `PlutusScript` -- `address` -- `slot` +#### PlutusData -#### `get_transaction` +##### By hash -#### `get_script_by_hash` +Request: -#### `get_datum_by_hash` +- hash: `DataHash` + +Response: + +- `PlutusData` + +#### Reward history + +##### By stake address + +TODO + +#### Block + +##### By hash + +Request: + +- `BlockHash` + +Response: + +- `Block` + +#### Epoch + +TODO + +#### Genesis + +TODO + +#### Metadata + +##### By transaction hash + +TODO + +#### Protocol parameters + +##### By epoch + +Request: + +- epoch: `UInt32` + +Response: + +- TODO: we should add `ProtocolParameters` to CIP-116 + +#### Stake pools + +##### List of active stake pools + +Request: + +- slot?: `UInt64` + +Response: + +``` +{ + pool_id: PoolPubKeyHash, + live_stake: UInt64, + active_stake: UInt64 +}[] +``` + +##### Get pool by ID + +Request: + +- pool_pubkey_hash: `PoolPubKeyHash` + +Response: + +- `PoolParams` + +### Transports + +TODO: specify how to go from the description above to consumable API specs. + +#### HTTP + +TBD + +#### WebSocket + +TBD + +#### Injected JavaScript object + +TBD ## Rationale: how does this CIP achieve its goals? + - +- [ ] There is at least one protocol adapter for any of the existing query layers that implements this spec, that can be run. +- [ ] There is at least one offchain library that implements a provider interface for this CIP, effectively making it usable with the protocol adapter in production. ### Implementation Plan +- [ ] Build at least one protocol adapter for any of the existing query layers that implements this spec +- [ ] Build at least one offchain library integration + ## Copyright - +This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). From 059fa58194eeb4be3108d70bbf2032963a0978ef Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Thu, 1 Aug 2024 19:54:49 +0400 Subject: [PATCH 3/4] Add a note on pagination --- CIP-XXXX/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index 8ee815f479..db559099c8 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -45,6 +45,8 @@ Customized chain followers, at least in principle, allow for "live" rollback han General purpose query layers can also handle rollbacks just fine, but they don't propagate rollback events to dApps, because they do not possess any dApp-specific info to determine if a dApp *needs* to handle a particular rollback. dApps that work with general-purpose query layers follow pull-based architecture, rather than event subscription-based, which means they just request data as needed, instead of reacting to blockchain events. +In the context of this API, rollbacks should be acknowledged as a source of potential inconsistency between data pieces returned by different queries. + #### Error handling Errors should be divided in two categories: @@ -54,6 +56,12 @@ Errors should be divided in two categories: This document should only cover domain errors. +#### Pagination + +In CIP-30, pagination is not reliable, because there is no guarantee that the set of UTxOs does not change between calls. This behavior is not suitable for DeFi: consistency should be prioritized, even though it's impossible to guarantee it (due to rollbacks). + +Stable pagination can be achieved by letting the user refer to a particular state in time from the recent past via a slot number. + ### Methods This section contains transport-agnostic method descriptions & their parameter lists. From 79937f5d7129c11324ccc681e2a1a944b80cba28 Mon Sep 17 00:00:00 2001 From: Vladimir Kalnitsky Date: Tue, 10 Sep 2024 15:51:55 +0400 Subject: [PATCH 4/4] Remove slots --- CIP-XXXX/README.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/CIP-XXXX/README.md b/CIP-XXXX/README.md index db559099c8..ad1046bf65 100644 --- a/CIP-XXXX/README.md +++ b/CIP-XXXX/README.md @@ -58,9 +58,7 @@ This document should only cover domain errors. #### Pagination -In CIP-30, pagination is not reliable, because there is no guarantee that the set of UTxOs does not change between calls. This behavior is not suitable for DeFi: consistency should be prioritized, even though it's impossible to guarantee it (due to rollbacks). - -Stable pagination can be achieved by letting the user refer to a particular state in time from the recent past via a slot number. +In CIP-30, pagination is not reliable, because there is no guarantee that the set of UTxOs does not change between calls. This behavior is not suitable for DeFi: consistency should be prioritized, and pagination should be avoided. ### Methods @@ -73,12 +71,15 @@ The payload formats used below are references to [CIP-0116 - Standard JSON encod #### UTxOs +Resource name: `utxo` + ##### By address +Endpoint name: `address` + Request: - address: `Address` -- slot?: `UInt64` Response: @@ -86,10 +87,11 @@ Response: ##### By payment credential +Endpoint name: `payment_credential` + Request: - credential: `Credential` -- slot?: `UInt64` Response: @@ -97,10 +99,11 @@ Response: ##### By staking credential +Endpoint name: `stake_credential` + Request: - credential: `Credential` -- slot?: `UInt64` Response: @@ -108,11 +111,12 @@ Response: ##### By asset +Endpoint name: `asset` + Request: - script_hash: `ScriptHash` - asset_name: `AssetName` -- slot?: `UInt64` Response: @@ -121,7 +125,6 @@ Response: ##### By transaction ID - transaction_hash: `TransactionHash` -- slot?: `UInt64` Response: @@ -129,8 +132,6 @@ Response: #### Transaction -TODO: decide if we want mempool transactions, want to forbid these, or it doesn't matter. - ##### By hash Request: @@ -141,6 +142,14 @@ Response: - `Transaction` +#### Transaction history + +##### By Address + +##### By payment credential + +##### By stake credential + #### Script ##### Native Script by hash @@ -223,10 +232,6 @@ Response: ##### List of active stake pools -Request: - -- slot?: `UInt64` - Response: ```