Cardano Smart DB

Memory is where fleeting moments turn to whispers, and scattered data finds its form.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

• Table of Contents
• Introduction
• Features
• The Smart DB Ecosystem
  • Core Library
  • Development Tools
  • Learning & Implementation Resources
  • Production Reference Implementation
• Documentation
• Getting Started
• Transaction Flow and Smart Selection
• Installation
• Usage
• Conclusion
• Cardano Catalyst Reports
• Contribution
• License
• Acknowledgements

Introduction

The Smart DB Library is a Node.js package designed to simplify the interaction between JavaScript entities, a database, and the Cardano blockchain. It enables developers to work with entities backed by a database and synced with the blockchain, providing a transparent and seamless experience.

Features

• Hooks and Stores: Provides useHooks and EasyPeasy stores to deal with wallet connection.
• Seamless Blockchain Integration: Simplify interactions with the Cardano blockchain using JavaScript entities.
• Automatic Synchronization: Automatically synchronizes the application after transactions are confirmed to reflect the latest blockchain state in the internal database. Users can also trigger synchronization manually if needed.
• Smart UTXO Management: Implements a sophisticated system for managing UTXOs, including distinction between reading and consuming UTXOs.
• Smart Selection Algorithm: Optimizes UTXO selection for transactions, maximizing throughput and minimizing conflicts in high-concurrency scenarios.
• Concurrent Transaction Handling: Robust system for managing multiple simultaneous transactions with minimal conflicts.
• Authorization: All API endpoints are secured with authorization logic using Next.js sessions and JWT tokens.
• API Handling: The library handles all API routes, reducing the complexity in the projects that use our library.
• Node.js Dependency: This is a Node.js library to add as a dependency in dApps projects.
• Database Flexibility: Now supports both non-relational databases (using MongoDB via Mongoose) and relational databases (using PostgreSQL via TypeORM), giving developers the flexibility to choose the most appropriate database solution for their project.
• Query Optimization:
  • Selective field retrieval for optimized data transfer
  • Sorting and pagination capabilities
    • Support for sorting by any field
    • Skip/limit pagination
• Database Optimization:
  • Support for database indexes on entities
  • Covered queries optimization for minimizing I/O operations
  • Performance monitoring and comparison tools
  • Comparative testing between optimized and non-optimized entities
• Token Metadata Management:
  • Automatic retrieval and storage of token metadata from BlockFrost API
  • Local database storage to eliminate repeated external calls
  • Efficient metadata lookup for frequently accessed tokens
• Developer Tools: Includes scaffolding tools for entity generation, example projects, and project templates
• Example Project: Includes a comprehensive example project in the example folder demonstrating the use of the library.

The Smart DB Ecosystem

The Smart DB library is supported by a comprehensive ecosystem of tools, templates, and examples designed to help developers build dApps on Cardano:

Core Library

• Cardano Smart DB (This Repository)
  • The core library providing the foundational functionality for building dApps on Cardano
  • Handles blockchain synchronization, UTXO management, database integration, and API generation
  • Implements Smart Selection algorithm for optimal transaction handling
  • Supports both MongoDB and PostgreSQL databases
  • Provides comprehensive testing tools for concurrency and performance

Development Tools

• Cardano SmartDB Scaffold
  • Automated tools for generating GraphQL schemas and code
  • Streamlines entity creation and boilerplate code generation
  • Generates consistent project structure following best practices
  • Reduces development time through intelligent code generation
  • Supports both MongoDB and PostgreSQL schema generation

Learning & Implementation Resources

• SmartDB Example Project

  • Basic example project demonstrating core Smart DB functionality
  • Clear examples of entity creation and blockchain synchronization
  • Includes comprehensive test suites for API endpoints
  • Demonstrates concurrency handling with Smart Selection
  • Perfect starting point for learning Smart DB concepts
  • Includes Swagger documentation for API testing

• SmartDB Project Template

  • Production-ready template for starting new Smart DB projects
  • Includes essential configurations and project structure
  • Step-by-step guide for building a basic project
  • Examples of common implementation patterns
  • Designed for quick project bootstrapping

Production Reference Implementation

• Cardano Simple Marketplace
  • Complete end-to-end implementation of a production dApp
  • Full-featured NFT marketplace with buy/sell functionality
  • Demonstrates advanced Smart DB features in a real-world context
  • Includes on-chain and off-chain integration
  • Showcases best practices for production deployment
  • Serves as a comprehensive reference implementation

Documentation

For comprehensive, structured documentation covering the entire Smart DB ecosystem, including detailed guides, tutorials, and API references, please visit our Gitbook Documentation.

The Gitbook documentation includes:

• Complete Smart DB library reference
• Step-by-step guides for the Scaffold tools
• Project template tutorials
• Marketplace implementation examples
• Best practices and common patterns
• Testing and deployment guides

While each repository contains its own README with specific information, the Gitbook serves as a unified resource where all documentation is organized and interconnected, making it easier to understand how all components work together.

Getting Started

To begin developing with Smart DB, we recommend the following path:

1. Review this repository's documentation to understand core concepts
2. Explore the Example Project to learn basic implementations
3. Use the Scaffold tools to generate your initial project structure
4. Reference the Project Template for implementation patterns
5. Study the Simple Marketplace for advanced usage and production patterns

Transaction Flow and Smart Selection

The Smart DB Library implements a sophisticated transaction flow that includes:

• Distinction between reading (reference) and consuming UTXOs.
• Smart selection of UTXOs to optimize transaction success and system throughput.
• Concurrent transaction handling with minimal conflicts.
• Automatic UTXO locking and release mechanisms.
• Detailed transaction state management.

For a comprehensive explanation of the transaction flow, smart UTXO management, and the smart selection algorithm, please refer to our Transaction Flow Documentation.

For detailed concurrency tests that rigorously assess the performance and reliability of the Smart UTXO and Smart Selection systems across various scenarios, please refer to our Concurrency Tests or within the GitBook.

Installation

Refer to Installation for detailed installation instructions.

Usage

For information on how to use the Smart DB Library, including setting up entities, configuring the backend, and handling API routes, please refer to our Usage Guide.

Conclusion

The Smart DB library bridges the gap between traditional web application development and blockchain-based data management. By abstracting complex blockchain operations into familiar JavaScript entity interactions, it offers a developer-friendly pathway to blockchain integration. The sophisticated transaction handling and UTXO management systems enable the development of high-performance, concurrent dApps on the Cardano blockchain.

Cardano Catalyst Reports

Here are the links to the Catalyst Milestone reports for the Cardano Smart DB project. Each report provides an update on the project's progress, achievements, and next steps for each milestone.

• Milestone 1 Report
• Milestone 2 Report
• Milestone 3 Report
• Milestone 4 Report
• Milestone 5 Report
• Milestone 6 Report
• Milestone 7 Report

For more details on our progress and achievements, please refer to each report.

Contribution

Contributions to the Cardano Smart DB are welcome. Whether you're looking to fix bugs, add new features, or improve documentation, your help is appreciated.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Acknowledgements

We express our deepest gratitude to the Cardano community for their unwavering support and valuable contributions to this project. This work is part of a funded project through Cardano Catalyst, a community-driven innovation platform. For more details on the proposal and its progress, please visit our proposal page on IdeaScale.