diff --git a/docs/cardano/getting-started/_category_.json b/docs/cardano/getting-started/_category_.json new file mode 100644 index 0000000..b030b8c --- /dev/null +++ b/docs/cardano/getting-started/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Getting Started", + "position": 1 +} + \ No newline at end of file diff --git a/docs/cardano/getting-started/cardano-cli.md b/docs/cardano/getting-started/cardano-cli.md new file mode 100644 index 0000000..df82d3e --- /dev/null +++ b/docs/cardano/getting-started/cardano-cli.md @@ -0,0 +1,224 @@ +--- +title: Cardano CLI +sidebar_position: 3 +hide_title: true +--- + +# Cardano CLI Quick Start + +## Prerequisites + +- **Cardano Node** – running and synchronized with your chosen network +- **Cardano CLI** – command-line interface (version 8.0+ for Conway era support) +- **Understanding** – Basic knowledge of UTxO model and public key cryptography + +--- + +## Environment Setup + +Configure these environment variables: + +```bash +# Path to your node socket +export CARDANO_NODE_SOCKET_PATH=/path/to/node.socket + +# Network ID +export CARDANO_NODE_NETWORK_ID=2 # Preview testnet (recommended for testing) +# export CARDANO_NODE_NETWORK_ID=1 # Preprod testnet +# export CARDANO_NODE_NETWORK_ID=4 # SanchoNet +# export CARDANO_NODE_NETWORK_ID=mainnet # Mainnet +``` + +### Network Selection + +:::note +If you did not set the `CARDANO_NODE_NETWORK_ID` environment variable, you **must** explicitly specify the target network with one of the flags below for every `cardano-cli` command. +::: + +```bash +# Preview testnet +--testnet-magic 2 + +# Preprod testnet +--testnet-magic 1 + +# SanchoNet (Conway testnet) +--testnet-magic 4 + +# Mainnet +--mainnet +``` + +Verify connection: + +```bash +cardano-cli latest query tip +``` + +--- + +## Key Generation + +Cardano uses Ed25519 cryptographic keys for securing funds and controlling stake delegation. + +### Payment Keys + +Payment keys control spending of UTxOs. Generate a payment key pair: + +```bash +cardano-cli latest address key-gen \ + --verification-key-file payment.vkey \ + --signing-key-file payment.skey +``` + +This creates: +- **`payment.skey`** – Private signing key (keep secure!) +- **`payment.vkey`** – Public verification key + +### Stake Keys + +Stake keys control delegation and reward withdrawal: + +```bash +cardano-cli latest stake-address key-gen \ + --verification-key-file stake.vkey \ + --signing-key-file stake.skey +``` + +### Key File Format + +Standard keys are stored as JSON text envelopes: + +```json +{ + "type": "PaymentVerificationKeyShelley_ed25519", + "description": "Payment Verification Key", + "cborHex": "5820..." +} +``` + +For programmatic use, you can extract key hashes: + +```bash +cardano-cli latest address key-hash \ + --payment-verification-key-file payment.vkey +``` + +--- + +## Building Addresses + +Cardano addresses encode payment and optional delegation rights. See [CIP-19](https://cips.cardano.org/cip/CIP-19) for the full specification. + +### Enterprise Address (Type 6) + +Payment-only address without staking capability: + +```bash +cardano-cli latest address build \ + --payment-verification-key-file payment.vkey \ + --out-file payment.addr \ +``` + +Use cases: +- Exchange hot wallets +- Smart contract addresses +- Simple payment flows + +### Base Address (Type 0) + +Full address with payment and delegation parts: + +```bash +cardano-cli latest address build \ + --payment-verification-key-file payment.vkey \ + --stake-verification-key-file stake.vkey \ + --out-file payment_stake.addr \ +``` + +Benefits: +- Can receive staking rewards +- Participate in delegation +- Standard for user wallets + +### Address Format + +View your generated address: + +```bash +cat payment.addr +``` + +Address prefixes indicate network: + +| Prefix | Type | Network | +| -------------- | --------------- | ------- | +| `addr1...` | Payment address | Mainnet | +| `addr_test1...`| Payment address | Testnet | +| `stake1...` | Stake address | Mainnet | +| `stake_test1...`| Stake address | Testnet | + +Example testnet addresses: + +``` +# Enterprise (no stake) +addr_test1vrqlsnsuz5j9kv8dp5s80pt0cgrm4m35kq0jxqw3usk7f8que2vlk + +# Base (with stake) +addr_test1qrqlsnsuz5j9kv8dp5s80pt0cgrm4m35kq0jxqw3usk7f8qhk0cxs4hnx7qpmsg4wwzrppt0atpjx7qyddep496mnecsr7f2g9 +``` + +--- + +## Querying the Blockchain + +### Check UTxOs + +Queries require a running node. Set the socket path: + +```bash +export CARDANO_NODE_SOCKET_PATH=/path/to/node.socket +``` + +Query unspent outputs at your address: + +```bash +cardano-cli latest query utxo \ + --address $(cat payment.addr) \ +``` + +Output format: +``` + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +262c7891f932cde390bcc04c25805f3f422c1a5687d5d47f6681e68bb384fe6d 0 10000000000 lovelace + TxOutDatumNone +``` + +--- + +## Getting Test ADA + +For new addresses without UTxOs: + +1. **Preview/Preprod Testnets** + - [Cardano Testnet Faucet](https://docs.cardano.org/cardano-testnets/tools/faucet) + - Provides test ADA via web interface + +2. **SanchoNet (Conway Features)** + - [SanchoNet Faucet](https://sancho.network/faucet) + - For testing governance and Conway era features + +3. **Verification** + ```bash + # After requesting funds, verify receipt + cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + ``` + +--- + +## Next Steps + +- [Simple Transactions](../transaction-building/simple-tx) – Build and submit transactions + +--- \ No newline at end of file diff --git a/docs/cardano/getting-started/overview.md b/docs/cardano/getting-started/overview.md new file mode 100644 index 0000000..e769bd3 --- /dev/null +++ b/docs/cardano/getting-started/overview.md @@ -0,0 +1,135 @@ +--- +title: Overview +sidebar_position: 1 +hide_title: true +--- + +# What is Cardano? + +Cardano is a third-generation blockchain platform designed to provide a more balanced and sustainable ecosystem for the future of money and decentralized applications. Founded by Charles Hoskinson, one of Ethereum's co-founders, Cardano takes a unique research-first approach to blockchain development. + +## Vision and Mission + +Cardano was created with a bold vision: **to provide economic identity to the billions who lack it**. The project aims to bring financial services to the developing world, enabling access to banking, loans, insurance, and investment opportunities for those currently excluded from the global financial system. + +### Core Mission +- Enable financial inclusion for underserved populations +- Create a platform for sustainable and transparent governance +- Build infrastructure for a fairer, more secure financial system +- Bridge the gap between traditional finance and blockchain technology + +## The Three Pillars + +Cardano is built on three fundamental pillars that guide its development: + +### 1. **Scalability** +The ability to grow and serve billions of users worldwide without compromising performance or accessibility. + +### 2. **Interoperability** +Creating bridges between different blockchains and traditional financial systems to enable seamless value transfer. + +### 3. **Sustainability** +Building a self-sustaining ecosystem that can fund its own development and evolve through community governance. + +## Why Cardano? + +### Academic Foundation +Cardano is the first blockchain platform to be built through peer-reviewed research. Every feature and protocol undergoes rigorous academic scrutiny before implementation, ensuring a solid theoretical foundation. + +### Real-World Focus +Unlike many blockchain projects focused on speculation, Cardano prioritizes solving real-world problems: +- Banking the unbanked +- Enabling secure voting systems +- Creating transparent supply chains +- Facilitating identity management + +### Long-Term Vision +Cardano is designed to last for decades, not years. Its governance model allows the platform to evolve and adapt to changing needs without requiring hard forks or causing community splits. + +## The Cardano Roadmap + +Cardano's development is organized into five eras, each named after historical figures: + +### **Byron** - The Foundation +Established the basic blockchain and allowed users to buy and transfer ADA. + +### **Shelley** - Decentralization +Transitioned to community-run stake pools, achieving true decentralization. + +### **Goguen** - Smart Contracts +Introduced programmability, allowing developers to build decentralized applications. + +### **Basho** - Optimization +Focuses on improving scalability and interoperability. + +### **Voltaire** - Self-Governance +Implements treasury and voting systems for community-driven development. + +## What Makes Cardano Different? + +### Research-Driven Development +Every aspect of Cardano is based on peer-reviewed academic research, bringing scientific rigor to blockchain development. + +### Environmental Sustainability +Cardano's proof-of-stake system uses 99% less energy than proof-of-work blockchains like Bitcoin. + +### Inclusive Design +Built with developing nations in mind, Cardano considers the needs of those without reliable internet or modern banking infrastructure. + +### Regulatory Awareness +Designed to work within existing regulatory frameworks while maintaining decentralization. + +### Community Governance +The platform will eventually be entirely governed by its community through a democratic voting system. + +## Core Values + +### **Transparency** +All development is done in the open, with public repositories and regular updates. + +### **Inclusivity** +Building solutions that work for everyone, regardless of location or economic status. + +### **Sustainability** +Creating systems that can maintain and improve themselves over time. + +### **Collaboration** +Working with governments, institutions, and communities to create positive change. + +## Use Cases + +Cardano enables a wide range of applications: + +- **Financial Services**: Lending, insurance, and savings for the unbanked +- **Supply Chain**: Tracking products from origin to consumer +- **Education**: Verifiable credentials and certificates +- **Healthcare**: Secure medical records and data sharing +- **Governance**: Transparent voting and decision-making systems +- **Digital Identity**: Self-sovereign identity solutions + +## Getting Started + +To begin your journey with Cardano: + +1. **Learn the basics**: Understand blockchain fundamentals and Cardano's approach +2. **Join the community**: Engage with developers, stake pool operators, and enthusiasts +3. **Explore the ecosystem**: Discover projects building on Cardano +4. **Start building**: Use Cardano's tools and resources to create your own solutions + +## The Future of Cardano + +Cardano's vision extends beyond being just another blockchain. It aims to become the financial operating system for the developing world, enabling: + +- Universal access to financial services +- Transparent and accountable governance +- Sustainable economic growth +- Preservation of individual privacy and rights + +By combining academic rigor, sustainable design, and a focus on real-world utility, Cardano is building the foundation for a more inclusive global economy. + +## Next Steps + +- Visit the [Cardano Foundation](https://cardanofoundation.org) for official resources +- Explore the [Cardano Forum](https://forum.cardano.org) to connect with the community +- Learn about [Project Catalyst](https://projectcatalyst.io) for funding opportunities +- Discover [projects building on Cardano](https://www.cardanocube.io) \ No newline at end of file diff --git a/docs/cardano/transaction-building/_category_.json b/docs/cardano/transaction-building/_category_.json new file mode 100644 index 0000000..a46a836 --- /dev/null +++ b/docs/cardano/transaction-building/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Transaction Building", + "position": 2 +} + \ No newline at end of file diff --git a/docs/cardano/transaction-building/simple-tx.md b/docs/cardano/transaction-building/simple-tx.md new file mode 100644 index 0000000..62be0bf --- /dev/null +++ b/docs/cardano/transaction-building/simple-tx.md @@ -0,0 +1,373 @@ +--- +title: Simple Transactions +sidebar_position: 1 +hide_title: true +--- + +# Simple Transactions + +## Prerequisites + +- **Cardano Node** – running and fully synchronized +- **Cardano CLI** – command-line interface to the node +- **Payment address with funds** – see [Cardano CLI Quick Start](../getting-started/cardano-cli) +- **Environment** – Variables set as shown in [Environment Setup](../getting-started/cardano-cli#environment-setup) + +--- + +## Understanding Cardano Transactions + +### UTxO Model + +Cardano uses the Unspent Transaction Output (UTxO) model. Each UTxO represents coins that can be spent and is uniquely identified by: +- **Transaction hash** (TxHash) – The ID of the transaction that created it +- **Output index** (TxIx) – Position in that transaction's outputs (starts at 0) + +Format: `TxHash#TxIx` (e.g., `4694ed...366b#0`) + +### Transaction Structure + +Every transaction must: +1. **Consume entire UTxOs** – You can't partially spend a UTxO +2. **Create new UTxOs** – Including change back to yourself +3. **Pay fees** – Deducted from the total inputs +4. **Balance perfectly** – `sum(inputs) = sum(outputs) + fee` + +### Build Methods + +| Method | Fee Calculation | Node Required | Use Case | +| ----------- | --------------- | ------------- | ----------------------------------- | +| `build-raw` | Manual | No (offline) | Air-gapped signing, precise control | +| `build` | Automatic | Yes | Quick transactions, convenience | + +--- + +## Method 1: Using build-raw (Manual) + +### Step 1: Query Protocol Parameters + +Protocol parameters are necessary for calculating the transaction fee at a later stage. + +```bash +cardano-cli latest query protocol-parameters --out-file pparams.json +``` + +### Step 2: Find Your UTxOs + +You will need to consume one or more UTxOs to build an actual transaction. + +```bash +cardano-cli latest query utxo --address $(cat payment.addr) +``` + +Example output: +``` + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b 0 10000000000 lovelace + TxOutDatumNone +``` + +### Step 3: Build Draft Transaction + +To send 1,000 ADA (1,000,000,000 lovelace) to another address: + +```bash +cardano-cli latest transaction build-raw \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --tx-out "$(cat payment1.addr)+9000000000" \ + --fee 0 \ + --protocol-params-file pparams.json \ + --out-file tx.draft +``` + +### Step 4: Calculate Minimum Fee + +:::warning Fee Calculation Issue +The `calculate-min-fee` command has a known issue where using `--fee 0` can result in underestimated fees. This happens because CBOR encoding uses fewer bytes for smaller values, affecting the transaction size. + +> **Workaround**: Use a larger dummy fee (e.g., 300000) when building your draft. This ensures the transaction size in the draft is similar to or larger than the final transaction, preventing fee underestimation: + +```bash +# Build draft with larger dummy fee to account for size changes +cardano-cli latest transaction build-raw \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --tx-out "$(cat payment1.addr)+8999700000" \ + --fee 300000 \ + --protocol-params-file pparams.json \ + --out-file tx.draft +``` + +The 300000 value isn't special – any reasonably large fee works to ensure proper size calculation. +::: + +Calculate the fee: + +```bash +cardano-cli latest transaction calculate-min-fee \ + --tx-body-file tx.draft \ + --protocol-params-file pparams.json \ + --witness-count 1 +``` + +**Output**: `167041 Lovelace` + +### Step 5: Build Final Transaction + +Calculate change: + +```bash +echo $((10000000000 - 1000000000 - 167041)) +``` + +**Output**: `8999832959` + +Build the final transaction with the newly calculated change: + +```bash +cardano-cli latest transaction build-raw \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --tx-out "$(cat payment1.addr)+8999832959" \ + --fee 167041 \ + --protocol-params-file pparams.json \ + --out-file tx.raw +``` + +### Step 6: Sign Transaction + +```bash +cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment1.skey \ + --out-file tx.signed +``` + +### Step 7: Submit Transaction + +```bash +cardano-cli latest transaction submit --tx-file tx.signed +``` + +Success output: +``` +Transaction successfully submitted. +``` + +--- + +## Method 2: Using build (Automatic) + +The `build` command simplifies the process by handling fee calculation automatically. + +### Step 1: Build Transaction + +```bash +cardano-cli latest transaction build \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --change-address $(cat payment1.addr) \ + --out-file tx.raw +``` + +Output: +``` +Estimated transaction fee: Lovelace 167041 +``` + +### Step 2: Sign and Submit + +```bash +# Sign +cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment1.skey \ + --out-file tx.signed + +# Submit +cardano-cli latest transaction submit --tx-file tx.signed +``` + +--- + +## Inspecting Transactions + +### View Transaction Structure + +Detailed human-readable format: + +```bash +cardano-cli debug transaction view --tx-body-file tx.raw # or tx.signed +``` + +Key fields to check: +- **inputs** – UTxOs being consumed +- **outputs** – New UTxOs being created +- **fee** – Transaction cost in lovelace +- **witnesses** – Empty until signed + +:::tip Inspecting raw CBOR +Need to peek under the hood? Use the web-based [CBOR Playground](https://cbor.nemo157.com/) to decode and explore a transaction’s CBOR. +1. Extract the CBOR blob from your unsigned or signed transaction: + +```bash +cat tx.signed +``` + +Example output (truncated): +```json +{ + "type": "Witnessed Tx ConwayEra", + "description": "Ledger Cddl Format", + "cborHex": "84a300d90102818258207b4586a8d82b...f5f6" +} +``` + +2. Copy the value of cborHex (everything inside the quotes). +3. Paste it into CBOR Playground to see the decoded structure. + +For a precise, field-by-field explanation, cross-reference the [latest Conway CDDL](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/conway/impl/cddl-files/conway.cddl). Together, the Playground and CDDL give you a clear, low-level view of how Cardano transactions are encoded. +::: + +### Get Transaction ID + +Before submission (from signed file): + +```bash +cardano-cli latest transaction txid --tx-file tx.signed +``` + +After submission: + +```bash +cardano-cli latest query utxo --tx-in # +``` + +--- + +## Common Patterns + +### Multiple Outputs + +Send to multiple recipients: + +```bash +cardano-cli latest transaction build \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat alice.addr)+500000000" \ + --tx-out "$(cat bob.addr)+300000000" \ + --tx-out "$(cat charlie.addr)+200000000" \ + --change-address $(cat payment1.addr) \ + --out-file tx.raw +``` + +### Using Multiple Inputs + +```bash +cardano-cli latest transaction build \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-in 42815054e2be3257326a1ba85e83cde9c41061883a06f824899db0d4ed8f3a66#1 \ + --tx-out "$(cat payment2.addr)+15000000000" \ + --change-address $(cat payment1.addr) \ + --out-file tx.raw +``` + +### Programmatic UTxO Selection + +```bash +# Get first UTxO as input +FIRST_UTXO=$(cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + --output-json | jq -r 'keys[0]') + +cardano-cli latest transaction build \ + --tx-in $FIRST_UTXO \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --change-address $(cat payment.addr) \ + --out-file tx.raw +``` + +--- + +## Troubleshooting + +### Node Connection Issues + +```bash +# Check node status +cardano-cli latest query tip + +# If not set, configure environment variables: +export CARDANO_NODE_SOCKET_PATH=/path/to/node.socket +export CARDANO_NODE_NETWORK_ID=2 # Preview testnet +``` + +### Insufficient Funds + +Always account for: +- Transaction amount +- Transaction fee (~0.17–0.2 ADA for simple transactions) +- Minimum UTxO value (~1 ADA per output) + +### Fee Too Small Errors + +If using `build-raw` and getting fee errors: +1. Use the 300000 fee workaround when calculating +2. Add a small buffer (5-10%) to calculated fees +3. Consider using `build` command instead + +--- + +## Complete Example + +Here's a real transaction from start to finish: + +```bash +# 1. Check balance +$ cardano-cli latest query utxo --address $(cat payment1.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b 0 10000000000 lovelace + +# 2. Build transaction (sending 1000 ADA) +$ cardano-cli latest transaction build \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --change-address $(cat payment1.addr) \ + --out-file tx.raw + +Estimated transaction fee: Lovelace 167041 + +# 3. Sign +$ cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment1.skey \ + --out-file tx.signed + +# 4. Submit +$ cardano-cli latest transaction submit --tx-file tx.signed +Transaction successfully submitted. + +# 5. Verify - Check both addresses +$ cardano-cli latest query utxo --address $(cat payment1.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +42815054e2be3257326a1ba85e83cde9c41061883a06f824899db0d4ed8f3a66 1 8999832959 lovelace + +$ cardano-cli latest query utxo --address $(cat payment2.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +42815054e2be3257326a1ba85e83cde9c41061883a06f824899db0d4ed8f3a66 0 1000000000 lovelace +``` + +Transaction breakdown: + +| Component | Amount | Description | +| ------------ | --------------- | ----------- | +| **Input** | 10,000 ADA | Total UTxO | +| **Output 1** | 1,000 ADA | Payment | +| **Output 2** | 8,999.832959 ADA| Change | +| **Fee** | 0.167041 ADA | Network fee | + +--- \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 31653ba..c8a2dc7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -142,6 +142,14 @@ const config: Config = { label: 'Buriza', className: "hover:text-[#227CFF]!" }, + { + docid: 'cardano', + type: 'docSidebar', + sidebarId: 'cardano', + position: 'left', + label: 'Cardano', + className: "hover:text-[#649DCA]!" + }, ], }, footer: { diff --git a/sidebars.ts b/sidebars.ts index 7f90d8b..6ffe747 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -21,6 +21,7 @@ const sidebars: SidebarsConfig = { comp: [{type: 'autogenerated', dirName: 'comp'}], futura: [{type: 'autogenerated', dirName: 'futura'}], buriza: [{type: 'autogenerated', dirName: 'buriza'}], + cardano: [{type: 'autogenerated', dirName: 'cardano'}], // argusSidebar: [ // 'argus/intro', // 'argus/getting-started',