docs: add Governance, Backend Services, and Supplier Interfaces APIs …#522
docs: add Governance, Backend Services, and Supplier Interfaces APIs …#522ducpm2303 wants to merge 6 commits intodocs/api-doc-improvementfrom
Conversation
…documentation - Introduced new documentation for Governance API, detailing DRep management, proposal creation, voting, and delegation. - Added Backend Services API documentation, covering integration with various backend services and usage examples. - Created Supplier Interfaces API documentation, outlining extensible interfaces for custom backend data providers and implementation examples.
satran004
left a comment
satran004
left a comment
There was a problem hiding this comment.
Thanks @ducpm2303 . Please check my comments
| .from(address); | ||
|
|
||
| Result<String> result = quickTxBuilder.compose(tx) | ||
| .withSigner(SignerProviders.drepKeySignerFrom(account)) |
There was a problem hiding this comment.
@ducpm2303 For proposal creation, drepKey signature is not required. Any account can create the proposal. I think we need to update integration tests also.
| .from(address); | ||
|
|
||
| Result<String> result = quickTxBuilder.compose(tx) | ||
| .withSigner(SignerProviders.drepKeySignerFrom(account)) |
There was a problem hiding this comment.
Please try it out and update all create proposal code snippet accordingly.
|
|
||
| # Backend Services API | ||
|
|
||
| The Backend Services API provides integration with various Cardano backend services through a unified interface. This allows applications to interact with the Cardano blockchain without running a local node, supporting multiple providers for flexibility and redundancy. |
There was a problem hiding this comment.
We can just keep this line, as in theory we could also have a back-end provider running on a local Cardano node.
| The Backend Services API provides integration with various Cardano backend services through a unified interface. This allows applications to interact with the Cardano blockchain without running a local node, supporting multiple providers for flexibility and redundancy. | |
| The Backend Services API provides integration with various Cardano backend services through a unified interface. |
|
|
||
| - **Unified Interface**: Single API for multiple backend providers | ||
| - **Provider Flexibility**: Switch between different backend services easily | ||
| - **Service Coverage**: Complete access to blockchain data and transaction services |
There was a problem hiding this comment.
Please remove "Complete". So it should be "Access to blockchain data and transaction services" as we don't support all the data yet. For example: Governance data
| - **Unified Interface**: Single API for multiple backend providers | ||
| - **Provider Flexibility**: Switch between different backend services easily | ||
| - **Service Coverage**: Complete access to blockchain data and transaction services | ||
| - **Network Support**: Mainnet, testnet, and preview network compatibility |
There was a problem hiding this comment.
Let's remove "Network Support", "Automatic Failover" and "Rate Limiting" as CCL doesn't directly control these.
| return new BFBackendService(endpoint, apiKey); | ||
| case "koios": | ||
| return new KoiosBackendService(endpoint); | ||
| case "ogmios": |
There was a problem hiding this comment.
We can add kupomios instead of ogmios. In that case, KupmiosBackendService will be used.
|
|
||
| # Supplier Interfaces API | ||
|
|
||
| The Supplier Interfaces API provides extensible interfaces for integrating custom data providers with the Cardano Client Library. These interfaces enable custom backend implementations, service extensions, and flexible provider switching for enhanced testability and integration capabilities. |
There was a problem hiding this comment.
We should explicitly mention that the Supplier interfaces provide the essential APIs required to build and submit transactions. These include:
- Getting UTxOs
- Fetching protocol parameters
- Evaluating transaction script costs
- Submitting transactions
This approach provides the quickest and clearest way to integrate any third-party data provider for transaction building and submission.
While the purpose of BackendService is similar, it provides many additional APIs that can be useful for a dApp or application, but are not strictly required for transaction building or submission. As a result, creating a new BackendService implementation requires more effort.
Additionally, the transaction builder APIs depend on the Supplier interfaces, rather than directly on BackendService. This provides the right level of abstraction to integrate any third-party provider with the transaction builder API.
| - `OgmiosTransactionProcessor` - Ogmios transaction processing | ||
| - `KupoUtxoSupplier` - Kupo-based UTXO provider | ||
| - `OgmiosTransactionEvaluator` - Ogmios script evaluation | ||
|
|
There was a problem hiding this comment.
Please mention DefaultUtxoSupplier, DefaultProtocolParamSupplier, and DefaultTransactionProcessor, which are the default implementations instantiated from BackendService and are currently set as the defaults for transaction building."
| ProtocolParamsSupplier protocolParamsSupplier = new CustomProtocolParamsSupplier(); | ||
|
|
||
| // Use with QuickTx | ||
| QuickTxBuilder quickTxBuilder = new QuickTxBuilder(customUtxoSupplier) |
There was a problem hiding this comment.
Can you please verify if fluent API support is available? I think you can only provide these suppliers through the QuickTxBuilder constructor.
| KupoUtxoSupplier kupoUtxoSupplier = new KupoUtxoSupplier("http://localhost:1442"); | ||
|
|
||
| // Use with QuickTx | ||
| QuickTxBuilder builder = new QuickTxBuilder(kupoUtxoSupplier); |
There was a problem hiding this comment.
Please verify this constructor if it exists
- Added support for the new "kupomios" backend service, which requires both Ogmios and Kupo URLs. - Updated usage examples to include the new "kupomios" service alongside existing examples for "blockfrost".
- Expanded the description of Supplier Interfaces to clarify their role in transaction building and submission. - Added detailed sections on core functionalities, default implementations, and third-party supplier integrations. - Updated usage examples for integrating custom suppliers with QuickTx, emphasizing constructor-based supplier provision. - Clarified the distinction between Supplier Interfaces and BackendService for better understanding of integration options.
- Simplified the description of the Backend Services API by removing redundant details. - Clarified the integration method for the Ogmios backend service, changing from WebSocket to HTTP. - Added a new section for Kupmios integration, detailing its usage and benefits for transaction building. - Updated usage examples to reflect the changes in service initialization and access methods.
|
ducpm2303
force-pushed
the
docs/gov-and-providers-doc
branch
from
7669f69 to
80b49e6
Compare
|
2 participants
#523