From 49139302b431c58239bb3572e8914f8f3950a1b2 Mon Sep 17 00:00:00 2001 From: Christian Benedict Gantuangco Date: Fri, 13 Jun 2025 00:06:06 +0800 Subject: [PATCH 1/4] docs(cardano): initial documentation structure --- docs/cardano/getting-started/_category_.json | 5 + docs/cardano/getting-started/overview.md | 135 +++++++++++++++++++ docusaurus.config.ts | 8 ++ sidebars.ts | 1 + 4 files changed, 149 insertions(+) create mode 100644 docs/cardano/getting-started/_category_.json create mode 100644 docs/cardano/getting-started/overview.md 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/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/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', From f399078f4c300971b4355df0793d673ed68ef548 Mon Sep 17 00:00:00 2001 From: Lance Vincent Salera Date: Fri, 13 Jun 2025 02:28:21 +0800 Subject: [PATCH 2/4] docs(cardano): add Cardano CLI and Simple Transactions documentation --- docs/cardano/getting-started/cardano-cli.md | 94 ++++ .../transaction-building/_category_.json | 5 + .../cardano/transaction-building/simple-tx.md | 438 ++++++++++++++++++ 3 files changed, 537 insertions(+) create mode 100644 docs/cardano/getting-started/cardano-cli.md create mode 100644 docs/cardano/transaction-building/_category_.json create mode 100644 docs/cardano/transaction-building/simple-tx.md diff --git a/docs/cardano/getting-started/cardano-cli.md b/docs/cardano/getting-started/cardano-cli.md new file mode 100644 index 0000000..406bd46 --- /dev/null +++ b/docs/cardano/getting-started/cardano-cli.md @@ -0,0 +1,94 @@ +--- +title: Cardano CLI +sidebar_position: 3 +hide_title: true +--- + +# Cardano CLI Quick Start + +## Prerequisites + +- Cardano Node – running or accessible on your machine +- Cardano CLI – the command-line interface to the node +- Basic Cardano concepts – e.g., UTxO model, network magic, keys & addresses + +--- + +## Generating Keys and Addresses + +:::info +For a complete overview of Cardano address types, read [CIP-19](https://cips.cardano.org/cip/CIP-19). +::: + +### Generating payment key pairs + +To generate a payment key pair, run: + +```bash +cardano-cli latest address key-gen \ +--verification-key-file payment.vkey \ +--signing-key-file payment.skey +``` + +To generate a stake key pair, run: + +```bash +cardano-cli latest stake-address key-gen \ +--verification-key-file stake.vkey \ +--signing-key-file stake.skey +``` + +:::info +- An address has two parts — Payment and Delegation (or Stake) part. +- Having a stake part of an address is purely optional. +- However, the address you will build without the stake part will have no staking rights thus cannot delegate or receive rewards. Your address will then only have the payment part. +- That means you can actually skip the stake key pair generation and all will still be good if you only need to do pure transactions! +::: + +### Building an address + +To build an address using the payment key pairs only, run: + +```bash +cardano-cli latest address build \ +--payment-verification-key-file payment.vkey \ +--out-file paymentNoStake.addr +``` + +To build an address with both payment and stake parts, run: + +```bash +cardano-cli address build \ +--payment-verification-key-file payment.vkey \ +--stake-verification-key-file stake.vkey \ +--out-file paymentWithStake.addr +``` + +Try displaying your generated address: + +```bash +cat payment.addr + +// `addr_test` means you have a Testnet Address. Mainnet addresses start with `addr`. +addr_test1qzdtyyt48yrn2fa3wvh939rat0gyv6ly0ljt449sw8tppzrcc3g0zu63cp6rnjumfcadft63x3w8ds4u28z6zlvra4fqy2sm8n +``` + +--- + +## Verify your address by querying your address balance + +```bash +cardano-cli query utxo --address $(< paymentNoStake.addr) + + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +262c7891f932cde390bcc04c25805f3f422c1a5687d5d47f6681e68bb384fe6d 0 10000000000 lovelace + TxOutDatumNone +``` + +:::tip +- If the list is empty, you probably don't have a UTxO yet which is normal with newly generated addresses. +- You can get test tokens for pre-production and preview testnets in this [Testnet Faucet](https://docs.cardano.org/cardano-testnets/tools/faucet) +- For SanchoNet tokens, go to the [SanchoNet faucet](https://sancho.network/faucet). +::: + +--- 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..fd1f77e --- /dev/null +++ b/docs/cardano/transaction-building/simple-tx.md @@ -0,0 +1,438 @@ +--- +title: Simple Transactions +sidebar_position: 1 +hide_title: true +--- + +# Simple Transactions + +## Prerequisites + +- Cardano Node – running +- Cardano CLI – the command-line interface to the node +- A generated address. If you haven't generated one yet, see [Cardano CLI Quick Start](../getting-started/cardano-cli) + +--- + +## Cardano Transactions Overview + +Cardano transactions involve consuming one or more Unspent Transaction Outputs (UTXOs) and generating one or more new UTXOs. The most basic transaction type involves transferring ada from one address to another. It is essential to ensure that all transactions are 'well-balanced', meaning that the sum of outputs and transaction fees equals the sum of inputs. This balance ensures the integrity and validity of the transaction. Unbalanced transactions are rejected by the local node. + +Creating a transaction using the CLI follows a three-step process: + + - Build: construct the transaction with relevant details + - Sign: authenticate the transaction with appropriate signatures + - Submit: send the signed transaction to the network for processing. + +You'll find commands for these tasks under `cardano-cli latest transaction` + +```bash +cardano-cli latest transaction +Usage: cardano-cli latest transaction + ( build-raw + | build + | build-estimate + | sign + | witness + | assemble + | submit + | policyid + | calculate-min-fee + | calculate-min-required-utxo + | hash-script-data + | txid + ) + + Transaction commands. +``` + +`cardano-cli` provides several options for constructing transactions: `transaction build-raw`, `transaction build`, and `build-estimate`. The key difference between these methods lies in their offline and online capabilities, as well as the degree of manual or automatic processing involved. + +- The `build-raw` command enables offline transaction building, eliminating the need for a connection to a running node. However, this method requires manual calculation of fees and balancing the transaction. +- The `build` command automatically calculates fees and balances the transaction, but it necessitates a connection to a running node +- The `build-estimate` command is a command that is useful for estimating the size and fee of a transaction when the CLI is not connected to the node. This command automatically balances a transaction related to the script one would like to execute. + +When building a transaction, it's essential to specify the following elements: + +- **Inputs**: one or multiple Unspent Transaction Outputs (UTXOs) being utilized +- **Outputs**: the addresses where the funds will be sent, including the amount in lovelace for each recipient and any change that needs to be returned to yourself +- **Transaction fee**: the fee paid for the transaction to be processed on the chain. + +--- + +## Building transactions with the build-raw command + +To create a transaction using build-raw, you will need the protocol parameters. These parameters are necessary for calculating the transaction fee at a later stage. Querying the protocol parameters requires a running node: + +```bash +cardano-cli latest query protocol-parameters --out-file pparams.json +``` + +You also need to know the inputs (UTXOs) you will use. A UTXO is identified by its transaction hash (TxHash) and transaction index (TxIx) with the syntax TxHash#TxIx. You can only use UTXOs controlled by your payment.skey. + +To query the UTXOs associated to your payment.addr, run: + +```bash +cardano-cli conway query utxo --address $(< payment.addr) + + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891 0 9994790937 lovelace + TxOutDatumNone +``` + +In this example, the address has one UTXO associated with it. It holds 9,994,790,937 lovelace (9,994.790937 ada). + +Assume you want to send 1,000,000 lovelace (1,000 ada) from payment.addr to a payment2.addr. This transaction will have one input and two outputs: + +- The single input is the UTXO that the transaction will consume, in this case e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 +- The first output corresponds to the 1000 ada we are sending to payment2.addr +- The second output corresponds to the change of the transaction. We are sending the difference (8994790937 lovelace) to payment.addr. + +At this stage, you do not need to worry about the transaction fees. Save the transaction body in the tx.draft file: + +```bash +cardano-cli latest transaction build-raw \ + --tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ + --tx-out addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30+1000000000 \ + --tx-out addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5+8994790937 \ + --fee 0 \ + --protocol-params-file pparams.json \ + --out-file tx.draft +``` + +cardano-cli can handle the nesting of commands. For example, you can use cat within cardano-cli to read the addresses directly from the file. + +```bash +cardano-cli latest transaction build-raw \ + --tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ + --tx-out "$(< payment2.addr)+1000000000" \ + --tx-out "$(< payment.addr)+8994790937" \ + --fee 0 \ + --protocol-params-file pparams.json \ + --out-file tx.draft +``` + +Let's explore the created tx.draft file. It is a text envelope. The 'type' field says that it is an Unwitnessed Babbage era transaction. 'Unwitnessed' means that it has not been signed yet. The "cborHex" field encodes all transaction details: + +```json +cat tx.draft +{ + "type": "Unwitnessed Tx BabbageEra", + "description": "Ledger Cddl Format", + "cborHex": "84a30081825820e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab812559403889100018282581d60b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f1a3b9aca008258390062573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c4208f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d31b0000000218219e190200a0f5f6" +} +``` + +Use the transaction view command to show the transaction body in a human-readable format: + +```bash +cardano-cli debug transaction view --tx-body-file tx.draft +``` + +```json +{ + "auxiliary scripts": null, + "certificates": null, + "collateral inputs": [], + "era": "Babbage", + "fee": "0 Lovelace", + "inputs": [ + "e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0" + ], + "metadata": null, + "mint": null, + "outputs": [ + { + "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", + "address era": "Shelley", + "amount": { + "lovelace": 1000000000 + }, + "network": "Testnet", + "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", + "reference script": null, + "stake reference": null + }, + { + "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", + "address era": "Shelley", + "amount": { + "lovelace": 8994790937 + }, + "network": "Testnet", + "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", + "reference script": null, + "stake reference": { + "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" + } + } + ], + "reference inputs": [], + "required signers (payment key hashes needed for scripts)": null, + "return collateral": null, + "total collateral": null, + "update proposal": null, + "validity range": { + "lower bound": null, + "upper bound": null + }, + "withdrawals": null, + "witnesses": [] +} +``` + +--- + +## Calculating transaction fees and balancing a transaction + +:::info +In Cardano, transaction fees are deterministic, meaning that you can know in advance how much a transaction will cost. +::: + +To process a transaction on the network, it must include fees specified within the transaction body. To calculate the exact cost, use the transaction calculate-min-fee command, which takes tx.draft and pparams.json files as inputs. Within this command, specify details like the total number of inputs, outputs, and the required number of signatures. In this case, only one witness, the payment.skey signature, is needed: + +```bash +cardano-cli latest transaction calculate-min-fee \ + --tx-body-file tx.draft \ + --protocol-params-file pparams.json \ + --witness-count 1 +``` + +Running the command returns the fee that needs to be paid: + +```bash +173993 Lovelace +``` + +With this, recalculate the change that needs to go to payment.addr with a simple operation: Change = originalBalance - amountSent - Fee: + +```bash +echo $((9994790937 - 1000000000 - 173993)) +8994616944 +``` + +Re-run transaction build-raw, include the fee, and adjust the change (the second tx-out). This completes the transaction body, and conventionally, it is saved into the tx.raw file. + +```bash +cardano-cli latest transaction build-raw \ + --tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ + --tx-out $(< payment2.addr)+1000000000 \ + --tx-out $(< payment.addr)+8994616944 \ + --fee 173993 \ + --protocol-params-file pparams.json \ + --out-file tx.raw +``` + +--- + +## Signing the transaction + +Sign the transaction with the transaction sign command. You must sign with the payment.skey that controls the UTXO you are trying to spend. This time, we produce the tx.signed file: + +```bash +cardano-cli conway transaction sign \ +--tx-body-file tx.raw \ +--signing-key-file payment.skey \ +--testnet-magic 2 \ +--out-file tx.signed +``` + +Inspecting tx.signed with transaction view reveals that the "witnesses" field is no longer empty; it now contains the signature. + +```bash +cardano-cli debug transaction view --tx-file tx.signed +``` + +```json +{ + "auxiliary scripts": null, + "certificates": null, + "collateral inputs": [], + "era": "Babbage", + "fee": "173993 Lovelace", + "inputs": [ + "e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0" + ], + "metadata": null, + "mint": null, + "outputs": [ + { + "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", + "address era": "Shelley", + "amount": { + "lovelace": 1000000000 + }, + "network": "Testnet", + "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", + "reference script": null, + "stake reference": null + }, + { + "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", + "address era": "Shelley", + "amount": { + "lovelace": 8994616944 + }, + "network": "Testnet", + "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", + "reference script": null, + "stake reference": { + "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" + } + } + ], + "reference inputs": [], + "required signers (payment key hashes needed for scripts)": null, + "return collateral": null, + "total collateral": null, + "update proposal": null, + "validity range": { + "lower bound": null, + "upper bound": null + }, + "withdrawals": null, + "witnesses": [ + { + "key": "VKey (VerKeyEd25519DSIGN \"8e090717d4c91437d3b8c467acc850197485913efdbfb48114a4d6cf0ca2dc02\")", + "signature": "SignedDSIGN (SigEd25519DSIGN \"897d4774e3da7a9ff92cbfb36ba03443bad0473a449cd65a4855e4e167e6800267d6b38ba836cab05420c3c5a781855ea92e0266be511e96217dd91050abcb06\")" + } + ] +} +``` + +--- + +## Submitting the transaction + +Submitting the transaction means sending it to the blockchain for processing by the stake pools and eventual inclusion in a block. While building and signing a transaction can be done without a running node, submitting the transaction requires an active connection to a running node. Use the tx.signed file: + +```bash +cardano-cli latest transaction submit \ + --tx-file tx.signed +Transaction successfully submitted. +``` + +--- + +## Building transactions with the build command + +Using the build command for transaction construction simplifies the process significantly. However, it requires an active connection to the node to obtain the protocol parameters in real time. These parameters are then used to automatically calculate the fee to be paid. Additionally, the build command offers the --change-address flag, which automatically balances the transaction by sending the change to the specified address. + +For example, let's send 500 ada (500000000 lovelace) to the payment2.addr. + +First, query the UTXOs of the input address: + +```bash +cardano-cli latest query utxo --address $(< payment.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38 1 8994616944 lovelace + TxOutDatumNone +``` + +Build the transaction: + +```bash +cardano-cli latest transaction build \ + --tx-in c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38#1 \ + --tx-out $(< payment2.addr)+500000000 \ + --change-address $(< payment.addr) \ + --out-file tx.raw +``` + +Running this command returns the cost of the transaction fee: + +```bash +Estimated transaction fee: Lovelace 167041 +``` + +Inspecting tx.raw with transaction view reveals that the transaction body already includes the fee, and the transaction is already balanced. + +```bash +cardano-cli debug transaction view --tx-file tx.raw +``` + +```json +{ + "auxiliary scripts": null, + "certificates": null, + "collateral inputs": [], + "era": "Babbage", + "fee": "167041 Lovelace", + "inputs": [ + "c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38#1" + ], + "metadata": null, + "mint": null, + "outputs": [ + { + "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", + "address era": "Shelley", + "amount": { + "lovelace": 500000000 + }, + "network": "Testnet", + "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", + "reference script": null, + "stake reference": null + }, + { + "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", + "address era": "Shelley", + "amount": { + "lovelace": 8494449903 + }, + "network": "Testnet", + "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", + "reference script": null, + "stake reference": { + "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" + } + } + ], + "reference inputs": [], + "required signers (payment key hashes needed for scripts)": null, + "return collateral": null, + "total collateral": null, + "update proposal": null, + "validity range": { + "lower bound": null, + "upper bound": null + }, + "withdrawals": null, + "witnesses": [] +} +``` + +--- + +## Signing the transaction + +As previously, sign the transaction with the payment.skey: + +```bash +cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment.skey \ + --out-file tx.signed +``` + +## Submitting the transaction + +```bash +cardano-cli latest transaction submit \ + --tx-file tx.signed + +Transaction successfully submitted. +``` + +:::info +You can parse cardano-cli JSON outputs with jq to create programmatic workflows. For example, you can parse the output of query utxo to obtain the first UTXO associated with the payment address and use it as input (--tx-in) in transaction build: + +```bash +cardano-cli latest transaction build \ +--tx-in $(cardano-cli query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \ +--tx-out $(< payment.addr)+500000000 \ +--change-address $(< payment.addr) \ +--out-file tx.raw +``` +:: \ No newline at end of file From 83568884e9cbcb89cf731ec0204e7cca5951d232 Mon Sep 17 00:00:00 2001 From: Lance Vincent Salera Date: Fri, 13 Jun 2025 06:09:30 +0800 Subject: [PATCH 3/4] docs(cardano): enhance Cardano CLI and Simple Transactions documentation with detailed setup and transaction processes --- docs/cardano/getting-started/cardano-cli.md | 232 ++++++-- .../cardano/transaction-building/simple-tx.md | 516 +++++++----------- 2 files changed, 402 insertions(+), 346 deletions(-) diff --git a/docs/cardano/getting-started/cardano-cli.md b/docs/cardano/getting-started/cardano-cli.md index 406bd46..fc17dde 100644 --- a/docs/cardano/getting-started/cardano-cli.md +++ b/docs/cardano/getting-started/cardano-cli.md @@ -8,87 +8,243 @@ hide_title: true ## Prerequisites -- Cardano Node – running or accessible on your machine -- Cardano CLI – the command-line interface to the node -- Basic Cardano concepts – e.g., UTxO model, network magic, keys & addresses +- **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 --- -## Generating Keys and Addresses +## Environment Setup -:::info -For a complete overview of Cardano address types, read [CIP-19](https://cips.cardano.org/cip/CIP-19). +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 +``` + +:::note +While these environment variables are standard, some commands may still require explicit `--testnet-magic` and `--socket-path` flags depending on your CLI version. ::: -### Generating payment key pairs +Verify connection: + +```bash +cardano-cli latest query tip --testnet-magic 2 +``` + +--- + +## Key Generation + +Cardano uses Ed25519 cryptographic keys for securing funds and controlling stake delegation. + +### Payment Keys -To generate a payment key pair, run: +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 + --verification-key-file payment.vkey \ + --signing-key-file payment.skey ``` -To generate a stake key pair, run: +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 + --verification-key-file stake.vkey \ + --signing-key-file stake.skey ``` -:::info -- An address has two parts — Payment and Delegation (or Stake) part. -- Having a stake part of an address is purely optional. -- However, the address you will build without the stake part will have no staking rights thus cannot delegate or receive rewards. Your address will then only have the payment part. -- That means you can actually skip the stake key pair generation and all will still be good if you only need to do pure transactions! -::: +### Key File Format + +Standard keys are stored as JSON text envelopes: + +```json +{ + "type": "PaymentVerificationKeyShelley_ed25519", + "description": "Payment Verification Key", + "cborHex": "5820..." +} +``` -### Building an address +For programmatic use, you can extract key hashes: -To build an address using the payment key pairs only, run: +```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 \ + --testnet-magic 2 +``` + +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 \ ---out-file paymentNoStake.addr + --payment-verification-key-file payment.vkey \ + --stake-verification-key-file stake.vkey \ + --out-file payment_stake.addr \ + --testnet-magic 2 ``` -To build an address with both payment and stake parts, run: +Benefits: +- Can receive staking rewards +- Participate in delegation +- Standard for user wallets + +### Network Selection + +Specify the target network: ```bash -cardano-cli address build \ ---payment-verification-key-file payment.vkey \ ---stake-verification-key-file stake.vkey \ ---out-file paymentWithStake.addr +# Preview testnet +--testnet-magic 2 + +# Preprod testnet +--testnet-magic 1 + +# SanchoNet (Conway testnet) +--testnet-magic 4 + +# Mainnet +--mainnet ``` -Try displaying your generated address: +### 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 -// `addr_test` means you have a Testnet Address. Mainnet addresses start with `addr`. -addr_test1qzdtyyt48yrn2fa3wvh939rat0gyv6ly0ljt449sw8tppzrcc3g0zu63cp6rnjumfcadft63x3w8ds4u28z6zlvra4fqy2sm8n +# Base (with stake) +addr_test1qrqlsnsuz5j9kv8dp5s80pt0cgrm4m35kq0jxqw3usk7f8qhk0cxs4hnx7qpmsg4wwzrppt0atpjx7qyddep496mnecsr7f2g9 ``` --- -## Verify your address by querying your address balance +## Querying the Blockchain + +### Check UTxOs + +Query unspent outputs at your address: ```bash -cardano-cli query utxo --address $(< paymentNoStake.addr) +cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + --testnet-magic 2 +``` +Output format: +``` TxHash TxIx Amount -------------------------------------------------------------------------------------- 262c7891f932cde390bcc04c25805f3f422c1a5687d5d47f6681e68bb384fe6d 0 10000000000 lovelace + TxOutDatumNone ``` -:::tip -- If the list is empty, you probably don't have a UTxO yet which is normal with newly generated addresses. -- You can get test tokens for pre-production and preview testnets in this [Testnet Faucet](https://docs.cardano.org/cardano-testnets/tools/faucet) -- For SanchoNet tokens, go to the [SanchoNet faucet](https://sancho.network/faucet). -::: +For programmatic use, request JSON output: + +```bash +cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + --testnet-magic 2 \ + --output-json | jq +``` + +### Node Connection + +Queries require a running node. Set the socket path: + +```bash +export CARDANO_NODE_SOCKET_PATH=/path/to/node.socket +``` + +Or specify explicitly: + +```bash +cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + --testnet-magic 2 \ + --socket-path /path/to/node.socket +``` + +--- + +## 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) \ + --testnet-magic 2 + ``` --- + +## Next Steps + +- [Simple Transactions](../transaction-building/simple-tx) – Build and submit transactions + +--- \ No newline at end of file diff --git a/docs/cardano/transaction-building/simple-tx.md b/docs/cardano/transaction-building/simple-tx.md index fd1f77e..b382f52 100644 --- a/docs/cardano/transaction-building/simple-tx.md +++ b/docs/cardano/transaction-building/simple-tx.md @@ -8,188 +8,97 @@ hide_title: true ## Prerequisites -- Cardano Node – running -- Cardano CLI – the command-line interface to the node -- A generated address. If you haven't generated one yet, see [Cardano CLI Quick Start](../getting-started/cardano-cli) +- **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) --- -## Cardano Transactions Overview +## Understanding Cardano Transactions -Cardano transactions involve consuming one or more Unspent Transaction Outputs (UTXOs) and generating one or more new UTXOs. The most basic transaction type involves transferring ada from one address to another. It is essential to ensure that all transactions are 'well-balanced', meaning that the sum of outputs and transaction fees equals the sum of inputs. This balance ensures the integrity and validity of the transaction. Unbalanced transactions are rejected by the local node. +### UTxO Model -Creating a transaction using the CLI follows a three-step process: +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) - - Build: construct the transaction with relevant details - - Sign: authenticate the transaction with appropriate signatures - - Submit: send the signed transaction to the network for processing. +Format: `TxHash#TxIx` (e.g., `4694ed...366b#0`) -You'll find commands for these tasks under `cardano-cli latest transaction` +### Transaction Structure -```bash -cardano-cli latest transaction -Usage: cardano-cli latest transaction - ( build-raw - | build - | build-estimate - | sign - | witness - | assemble - | submit - | policyid - | calculate-min-fee - | calculate-min-required-utxo - | hash-script-data - | txid - ) - - Transaction commands. -``` - -`cardano-cli` provides several options for constructing transactions: `transaction build-raw`, `transaction build`, and `build-estimate`. The key difference between these methods lies in their offline and online capabilities, as well as the degree of manual or automatic processing involved. +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` -- The `build-raw` command enables offline transaction building, eliminating the need for a connection to a running node. However, this method requires manual calculation of fees and balancing the transaction. -- The `build` command automatically calculates fees and balances the transaction, but it necessitates a connection to a running node -- The `build-estimate` command is a command that is useful for estimating the size and fee of a transaction when the CLI is not connected to the node. This command automatically balances a transaction related to the script one would like to execute. +### Build Methods -When building a transaction, it's essential to specify the following elements: - -- **Inputs**: one or multiple Unspent Transaction Outputs (UTXOs) being utilized -- **Outputs**: the addresses where the funds will be sent, including the amount in lovelace for each recipient and any change that needs to be returned to yourself -- **Transaction fee**: the fee paid for the transaction to be processed on the chain. +| Method | Fee Calculation | Node Required | Use Case | +| ----------- | --------------- | ------------- | ----------------------------------- | +| `build-raw` | Manual | No (offline) | Air-gapped signing, precise control | +| `build` | Automatic | Yes | Quick transactions, convenience | --- -## Building transactions with the build-raw command +## Method 1: Using build-raw (Manual) -To create a transaction using build-raw, you will need the protocol parameters. These parameters are necessary for calculating the transaction fee at a later stage. Querying the protocol parameters requires a running node: +### Step 1: Query Protocol Parameters ```bash cardano-cli latest query protocol-parameters --out-file pparams.json ``` -You also need to know the inputs (UTXOs) you will use. A UTXO is identified by its transaction hash (TxHash) and transaction index (TxIx) with the syntax TxHash#TxIx. You can only use UTXOs controlled by your payment.skey. - -To query the UTXOs associated to your payment.addr, run: +### Step 2: Find Your UTxOs ```bash -cardano-cli conway query utxo --address $(< payment.addr) +cardano-cli latest query utxo --address $(cat payment.addr) +``` +Example output: +``` TxHash TxIx Amount -------------------------------------------------------------------------------------- -e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891 0 9994790937 lovelace + TxOutDatumNone +4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b 0 10000000000 lovelace + TxOutDatumNone ``` -In this example, the address has one UTXO associated with it. It holds 9,994,790,937 lovelace (9,994.790937 ada). - -Assume you want to send 1,000,000 lovelace (1,000 ada) from payment.addr to a payment2.addr. This transaction will have one input and two outputs: - -- The single input is the UTXO that the transaction will consume, in this case e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 -- The first output corresponds to the 1000 ada we are sending to payment2.addr -- The second output corresponds to the change of the transaction. We are sending the difference (8994790937 lovelace) to payment.addr. +### Step 3: Build Draft Transaction -At this stage, you do not need to worry about the transaction fees. Save the transaction body in the tx.draft file: +To send 1,000 ADA (1,000,000,000 lovelace) to another address: ```bash cardano-cli latest transaction build-raw \ - --tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ - --tx-out addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30+1000000000 \ - --tx-out addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5+8994790937 \ + --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 ``` -cardano-cli can handle the nesting of commands. For example, you can use cat within cardano-cli to read the addresses directly from the file. +### 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 e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ - --tx-out "$(< payment2.addr)+1000000000" \ - --tx-out "$(< payment.addr)+8994790937" \ - --fee 0 \ + --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 ``` -Let's explore the created tx.draft file. It is a text envelope. The 'type' field says that it is an Unwitnessed Babbage era transaction. 'Unwitnessed' means that it has not been signed yet. The "cborHex" field encodes all transaction details: - -```json -cat tx.draft -{ - "type": "Unwitnessed Tx BabbageEra", - "description": "Ledger Cddl Format", - "cborHex": "84a30081825820e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab812559403889100018282581d60b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f1a3b9aca008258390062573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c4208f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d31b0000000218219e190200a0f5f6" -} -``` - -Use the transaction view command to show the transaction body in a human-readable format: - -```bash -cardano-cli debug transaction view --tx-body-file tx.draft -``` - -```json -{ - "auxiliary scripts": null, - "certificates": null, - "collateral inputs": [], - "era": "Babbage", - "fee": "0 Lovelace", - "inputs": [ - "e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0" - ], - "metadata": null, - "mint": null, - "outputs": [ - { - "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", - "address era": "Shelley", - "amount": { - "lovelace": 1000000000 - }, - "network": "Testnet", - "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", - "reference script": null, - "stake reference": null - }, - { - "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", - "address era": "Shelley", - "amount": { - "lovelace": 8994790937 - }, - "network": "Testnet", - "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", - "reference script": null, - "stake reference": { - "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" - } - } - ], - "reference inputs": [], - "required signers (payment key hashes needed for scripts)": null, - "return collateral": null, - "total collateral": null, - "update proposal": null, - "validity range": { - "lower bound": null, - "upper bound": null - }, - "withdrawals": null, - "witnesses": [] -} -``` - ---- - -## Calculating transaction fees and balancing a transaction - -:::info -In Cardano, transaction fees are deterministic, meaning that you can know in advance how much a transaction will cost. +The 300000 value isn't special – any reasonably large fee works to ensure proper size calculation. ::: -To process a transaction on the network, it must include fees specified within the transaction body. To calculate the exact cost, use the transaction calculate-min-fee command, which takes tx.draft and pparams.json files as inputs. Within this command, specify details like the total number of inputs, outputs, and the required number of signatures. In this case, only one witness, the payment.skey signature, is needed: +Calculate the fee: ```bash cardano-cli latest transaction calculate-min-fee \ @@ -198,241 +107,232 @@ cardano-cli latest transaction calculate-min-fee \ --witness-count 1 ``` -Running the command returns the fee that needs to be paid: +Output: `167041 Lovelace` + +### Step 5: Build Final Transaction + +Calculate change: `10000000000 - 1000000000 - 167041 = 8999832959` ```bash -173993 Lovelace +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 ``` -With this, recalculate the change that needs to go to payment.addr with a simple operation: Change = originalBalance - amountSent - Fee: +### Step 6: Sign Transaction ```bash -echo $((9994790937 - 1000000000 - 173993)) -8994616944 +cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment1.skey \ + --out-file tx.signed ``` -Re-run transaction build-raw, include the fee, and adjust the change (the second tx-out). This completes the transaction body, and conventionally, it is saved into the tx.raw file. +### Step 7: Submit Transaction ```bash -cardano-cli latest transaction build-raw \ - --tx-in e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0 \ - --tx-out $(< payment2.addr)+1000000000 \ - --tx-out $(< payment.addr)+8994616944 \ - --fee 173993 \ - --protocol-params-file pparams.json \ - --out-file tx.raw +cardano-cli latest transaction submit --tx-file tx.signed +``` + +Success output: +``` +Transaction successfully submitted. ``` --- -## Signing the transaction +## Method 2: Using build (Automatic) -Sign the transaction with the transaction sign command. You must sign with the payment.skey that controls the UTXO you are trying to spend. This time, we produce the tx.signed file: +The `build` command simplifies the process by handling fee calculation automatically. + +### Step 1: Build Transaction ```bash -cardano-cli conway transaction sign \ ---tx-body-file tx.raw \ ---signing-key-file payment.skey \ ---testnet-magic 2 \ ---out-file tx.signed +cardano-cli latest transaction build \ + --tx-in 4694eddc13d7fab25722acc0a35bfdca4435a3b99830fb1723cb2e94478d366b#0 \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --change-address $(cat payment1.addr) \ + --out-file tx.raw ``` -Inspecting tx.signed with transaction view reveals that the "witnesses" field is no longer empty; it now contains the signature. +Output: +``` +Estimated transaction fee: Lovelace 167041 +``` + +### Step 2: Sign and Submit ```bash -cardano-cli debug transaction view --tx-file tx.signed -``` +# Sign +cardano-cli latest transaction sign \ + --tx-body-file tx.raw \ + --signing-key-file payment1.skey \ + --out-file tx.signed -```json -{ - "auxiliary scripts": null, - "certificates": null, - "collateral inputs": [], - "era": "Babbage", - "fee": "173993 Lovelace", - "inputs": [ - "e29e96a012c2443d59f2e53c156503a857c2f27c069ae003dab8125594038891#0" - ], - "metadata": null, - "mint": null, - "outputs": [ - { - "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", - "address era": "Shelley", - "amount": { - "lovelace": 1000000000 - }, - "network": "Testnet", - "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", - "reference script": null, - "stake reference": null - }, - { - "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", - "address era": "Shelley", - "amount": { - "lovelace": 8994616944 - }, - "network": "Testnet", - "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", - "reference script": null, - "stake reference": { - "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" - } - } - ], - "reference inputs": [], - "required signers (payment key hashes needed for scripts)": null, - "return collateral": null, - "total collateral": null, - "update proposal": null, - "validity range": { - "lower bound": null, - "upper bound": null - }, - "withdrawals": null, - "witnesses": [ - { - "key": "VKey (VerKeyEd25519DSIGN \"8e090717d4c91437d3b8c467acc850197485913efdbfb48114a4d6cf0ca2dc02\")", - "signature": "SignedDSIGN (SigEd25519DSIGN \"897d4774e3da7a9ff92cbfb36ba03443bad0473a449cd65a4855e4e167e6800267d6b38ba836cab05420c3c5a781855ea92e0266be511e96217dd91050abcb06\")" - } - ] -} +# Submit +cardano-cli latest transaction submit --tx-file tx.signed ``` --- -## Submitting the transaction +## Inspecting Transactions -Submitting the transaction means sending it to the blockchain for processing by the stake pools and eventual inclusion in a block. While building and signing a transaction can be done without a running node, submitting the transaction requires an active connection to a running node. Use the tx.signed file: +### View Transaction Structure + +Detailed human-readable format: ```bash -cardano-cli latest transaction submit \ - --tx-file tx.signed -Transaction successfully submitted. +cardano-cli debug transaction view --tx-body-file tx.raw ``` ---- +Key fields to check: +- **inputs** – UTxOs being consumed +- **outputs** – New UTxOs being created +- **fee** – Transaction cost in lovelace +- **witnesses** – Empty until signed -## Building transactions with the build command +### Get Transaction ID -Using the build command for transaction construction simplifies the process significantly. However, it requires an active connection to the node to obtain the protocol parameters in real time. These parameters are then used to automatically calculate the fee to be paid. Additionally, the build command offers the --change-address flag, which automatically balances the transaction by sending the change to the specified address. +Before submission (from signed file): -For example, let's send 500 ada (500000000 lovelace) to the payment2.addr. +```bash +cardano-cli latest transaction txid --tx-file tx.signed +``` -First, query the UTXOs of the input address: +After submission: ```bash -cardano-cli latest query utxo --address $(< payment.addr) - TxHash TxIx Amount --------------------------------------------------------------------------------------- -c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38 1 8994616944 lovelace + TxOutDatumNone +cardano-cli latest query utxo --tx-in # ``` -Build the transaction: +--- + +## Common Patterns + +### Multiple Outputs + +Send to multiple recipients: ```bash cardano-cli latest transaction build \ - --tx-in c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38#1 \ - --tx-out $(< payment2.addr)+500000000 \ - --change-address $(< payment.addr) \ + --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 ``` -Running this command returns the cost of the transaction fee: +### Using Multiple Inputs ```bash -Estimated transaction fee: Lovelace 167041 +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 ``` -Inspecting tx.raw with transaction view reveals that the transaction body already includes the fee, and the transaction is already balanced. +### Programmatic UTxO Selection ```bash -cardano-cli debug transaction view --tx-file tx.raw -``` +# Get first UTxO as input +FIRST_UTXO=$(cardano-cli latest query utxo \ + --address $(cat payment.addr) \ + --output-json | jq -r 'keys[0]') -```json -{ - "auxiliary scripts": null, - "certificates": null, - "collateral inputs": [], - "era": "Babbage", - "fee": "167041 Lovelace", - "inputs": [ - "c57f25ebf9cf1487b13deeb8449215c499f3d61c2836d84ab92a73b0bbaadd38#1" - ], - "metadata": null, - "mint": null, - "outputs": [ - { - "address": "addr_test1vzuztsedkqanfm7elu9nshfr4gh2gl0aj4djmayav2t7x8ch3pg30", - "address era": "Shelley", - "amount": { - "lovelace": 500000000 - }, - "network": "Testnet", - "payment credential key hash": "b825c32db03b34efd9ff0b385d23aa2ea47dfd955b2df49d6297e31f", - "reference script": null, - "stake reference": null - }, - { - "address": "addr_test1qp39w0fa0ccdc4gmg87puydf2kxt5mgt0vteq4a22ktrcssg7ysmx64l90xa0k4z25wpuejngya833qeu9cdxvveynfscsskf5", - "address era": "Shelley", - "amount": { - "lovelace": 8494449903 - }, - "network": "Testnet", - "payment credential key hash": "62573d3d7e30dc551b41fc1e11a9558cba6d0b7b179057aa55963c42", - "reference script": null, - "stake reference": { - "stake credential key hash": "08f121b36abf2bcdd7daa2551c1e6653413a78c419e170d3319924d3" - } - } - ], - "reference inputs": [], - "required signers (payment key hashes needed for scripts)": null, - "return collateral": null, - "total collateral": null, - "update proposal": null, - "validity range": { - "lower bound": null, - "upper bound": null - }, - "withdrawals": null, - "witnesses": [] -} +cardano-cli latest transaction build \ + --tx-in $FIRST_UTXO \ + --tx-out "$(cat payment2.addr)+1000000000" \ + --change-address $(cat payment.addr) \ + --out-file tx.raw ``` --- -## Signing the transaction +## Troubleshooting -As previously, sign the transaction with the payment.skey: +### Node Connection Issues ```bash -cardano-cli latest transaction sign \ - --tx-body-file tx.raw \ - --signing-key-file payment.skey \ - --out-file tx.signed +# 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 ``` -## Submitting the transaction +### 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 -cardano-cli latest transaction submit \ - --tx-file tx.signed +# 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. -``` -:::info -You can parse cardano-cli JSON outputs with jq to create programmatic workflows. For example, you can parse the output of query utxo to obtain the first UTXO associated with the payment address and use it as input (--tx-in) in transaction build: +# 5. Verify - Check both addresses +$ cardano-cli latest query utxo --address $(cat payment1.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +42815054e2be3257326a1ba85e83cde9c41061883a06f824899db0d4ed8f3a66 1 8999832959 lovelace -```bash -cardano-cli latest transaction build \ ---tx-in $(cardano-cli query utxo --address $(< payment.addr) --output-json | jq -r 'keys[0]') \ ---tx-out $(< payment.addr)+500000000 \ ---change-address $(< payment.addr) \ ---out-file tx.raw +$ cardano-cli latest query utxo --address $(cat payment2.addr) + TxHash TxIx Amount +-------------------------------------------------------------------------------------- +42815054e2be3257326a1ba85e83cde9c41061883a06f824899db0d4ed8f3a66 0 1000000000 lovelace ``` -:: \ No newline at end of file + +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 From 54f8de925d8148a40308a0d7f75f298476fa2ffb Mon Sep 17 00:00:00 2001 From: Lance Vincent Salera Date: Sat, 14 Jun 2025 01:27:31 +0800 Subject: [PATCH 4/4] docs(cardano): enhance Cardano CLI documentation with additional context on protocol parameters and UTxOs for transaction building --- docs/cardano/getting-started/cardano-cli.md | 76 ++++++------------- .../cardano/transaction-building/simple-tx.md | 43 ++++++++++- 2 files changed, 64 insertions(+), 55 deletions(-) diff --git a/docs/cardano/getting-started/cardano-cli.md b/docs/cardano/getting-started/cardano-cli.md index fc17dde..df82d3e 100644 --- a/docs/cardano/getting-started/cardano-cli.md +++ b/docs/cardano/getting-started/cardano-cli.md @@ -29,14 +29,30 @@ export CARDANO_NODE_NETWORK_ID=2 # Preview testnet (recommended for testi # export CARDANO_NODE_NETWORK_ID=mainnet # Mainnet ``` -:::note -While these environment variables are standard, some commands may still require explicit `--testnet-magic` and `--socket-path` flags depending on your CLI version. +### 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 --testnet-magic 2 +cardano-cli latest query tip ``` --- @@ -102,7 +118,6 @@ Payment-only address without staking capability: cardano-cli latest address build \ --payment-verification-key-file payment.vkey \ --out-file payment.addr \ - --testnet-magic 2 ``` Use cases: @@ -119,7 +134,6 @@ cardano-cli latest address build \ --payment-verification-key-file payment.vkey \ --stake-verification-key-file stake.vkey \ --out-file payment_stake.addr \ - --testnet-magic 2 ``` Benefits: @@ -127,24 +141,6 @@ Benefits: - Participate in delegation - Standard for user wallets -### Network Selection - -Specify the target network: - -```bash -# Preview testnet ---testnet-magic 2 - -# Preprod testnet ---testnet-magic 1 - -# SanchoNet (Conway testnet) ---testnet-magic 4 - -# Mainnet ---mainnet -``` - ### Address Format View your generated address: @@ -178,12 +174,17 @@ addr_test1qrqlsnsuz5j9kv8dp5s80pt0cgrm4m35kq0jxqw3usk7f8qhk0cxs4hnx7qpmsg4wwzrpp ### 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) \ - --testnet-magic 2 ``` Output format: @@ -193,32 +194,6 @@ Output format: 262c7891f932cde390bcc04c25805f3f422c1a5687d5d47f6681e68bb384fe6d 0 10000000000 lovelace + TxOutDatumNone ``` -For programmatic use, request JSON output: - -```bash -cardano-cli latest query utxo \ - --address $(cat payment.addr) \ - --testnet-magic 2 \ - --output-json | jq -``` - -### Node Connection - -Queries require a running node. Set the socket path: - -```bash -export CARDANO_NODE_SOCKET_PATH=/path/to/node.socket -``` - -Or specify explicitly: - -```bash -cardano-cli latest query utxo \ - --address $(cat payment.addr) \ - --testnet-magic 2 \ - --socket-path /path/to/node.socket -``` - --- ## Getting Test ADA @@ -238,7 +213,6 @@ For new addresses without UTxOs: # After requesting funds, verify receipt cardano-cli latest query utxo \ --address $(cat payment.addr) \ - --testnet-magic 2 ``` --- diff --git a/docs/cardano/transaction-building/simple-tx.md b/docs/cardano/transaction-building/simple-tx.md index b382f52..62be0bf 100644 --- a/docs/cardano/transaction-building/simple-tx.md +++ b/docs/cardano/transaction-building/simple-tx.md @@ -46,12 +46,16 @@ Every transaction must: ### 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) ``` @@ -82,7 +86,7 @@ cardano-cli latest transaction build-raw \ :::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: +> **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 @@ -107,11 +111,19 @@ cardano-cli latest transaction calculate-min-fee \ --witness-count 1 ``` -Output: `167041 Lovelace` +**Output**: `167041 Lovelace` ### Step 5: Build Final Transaction -Calculate change: `10000000000 - 1000000000 - 167041 = 8999832959` +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 \ @@ -186,7 +198,7 @@ cardano-cli latest transaction submit --tx-file tx.signed Detailed human-readable format: ```bash -cardano-cli debug transaction view --tx-body-file tx.raw +cardano-cli debug transaction view --tx-body-file tx.raw # or tx.signed ``` Key fields to check: @@ -195,6 +207,29 @@ Key fields to check: - **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):