Correct fee history, script hash detail, and finality figures

Author: 0xBora

docs/developers/curriculum/dapps/listen-for-payments.md

@@ -109,7 +109,7 @@ function receivedLovelace(addr) {
 For a complete point-of-sale app with a React UI, QR codes, and live USD/ADA conversion, fork the [Cardano POS starter](https://github.com/fill-the-fill/cardano-pos-starting-point).
 
 :::tip Wait for confirmations
-A transaction in a recent block can still be [rolled back](/docs/developers/curriculum/fundamentals/consensus-and-ouroboros#how-does-finality-work). Cardano produces a block roughly every 20 seconds, so for anything valuable wait 10-20 blocks (a few minutes) before treating a payment as final; the larger the amount, the deeper you should wait. Track deposits by transaction id and credit each one exactly once, only after your chosen depth, so a rollback that replays the same transaction cannot double-credit.
+A transaction in a recent block can still be [rolled back](/docs/developers/curriculum/fundamentals/consensus-and-ouroboros#how-does-finality-work). Cardano produces a block roughly every 20 seconds, so for anything valuable, wait 10-20 blocks (a few minutes) before treating a payment as final; the larger the amount, the deeper you should wait. Track deposits by transaction id and credit each one exactly once, only after your chosen depth, so a rollback that replays the same transaction cannot double-credit.
 :::
 
 ## Requesting a payment

docs/developers/curriculum/fundamentals/consensus-and-ouroboros.md

@@ -97,7 +97,7 @@ Short forks happen for two mundane reasons, and naming them removes the mystery.
 
 When a leader produces a block it must reach other nodes fast (Cardano targets diffusion within ~5 seconds) or risk being orphaned. The parameter **k** (currently 2160) defines settlement: a block is considered settled once k blocks follow it, roughly 12 hours at ~20s/block. And k is not only a probability statement: nodes never adopt a chain that forks more than k blocks below their tip, so everything deeper than k is immutable by construction and only the last k blocks are ever up for revision.
 
-In practice real forks are one or two blocks deep. Most applications treat 10-20 confirmations (a few minutes) as very safe for ordinary value; high-value receivers wait deeper, exchanges commonly 20-30 blocks or more; k is the absolute bound. The [Cardano Blueprint's chain selection page](https://cardano-scaling.github.io/cardano-blueprint/consensus/chainsel.html) covers the rule and its tie-breakers in detail.
+In practice forks are typically a block or two deep. Most applications treat 10-20 confirmations (a few minutes) as very safe for ordinary value; high-value receivers wait deeper, exchanges commonly 20-30 blocks or more; k is the absolute bound. The [Cardano Blueprint's chain selection page](https://cardano-scaling.github.io/cardano-blueprint/consensus/chainsel.html) covers the rule and its tie-breakers in detail.
 
 ### How do rewards and incentives drive decentralization?
 
@@ -113,13 +113,13 @@ Decentralization is not enforced by a rule; it emerges from economic incentives
 
 ## How does finality work?
 
-Cardano provides **probabilistic finality**: the chance of reversal decreases exponentially with each block added, and beyond k = 2160 blocks (~12 hours) reversal is impossible by construction, not merely unlikely. Practical finality is reached in 5-10 minutes.
+Cardano provides **probabilistic finality**: the chance of reversal decreases exponentially with each block added, and beyond k = 2160 blocks (~12 hours) chain selection refuses to roll back at all, making k a hard bound on rollback depth rather than a probability. Practical finality is 10-20 confirmations, a few minutes.
 
 | Network | Typical finality | Mechanism |
 |---|---|---|
 | Bitcoin (PoW) | ~60 min (6 blocks) | Probabilistic |
 | Ethereum (PoS) | ~15 min | Deterministic after finalization |
-| Cardano (Praos) | ~5-10 min practical, ~12h bound | Probabilistic, stake-based |
+| Cardano (Praos) | ~3-7 min practical, ~12h bound | Probabilistic, stake-based |
 
 ## What happens during a complete epoch?
 

docs/developers/curriculum/fundamentals/core-concepts/fees.md

@@ -2,10 +2,10 @@
 id: fees
 title: Transaction Fees
 sidebar_label: Transaction fees
-description: Cardano's deterministic fee formula, script execution costs, and collateral.
+description: Cardano's deterministic fee formula, script execution and reference script costs, and collateral.
 ---
 
-Transaction fees on Cardano are deterministic and predictable. They are calculated from a simple linear formula based on transaction size (plus script execution cost), so you can compute the exact fee before submitting, with no auctions and no gas-price spikes.
+Transaction fees on Cardano are deterministic and predictable. They are calculated from a simple linear formula based on transaction size (plus script execution and reference script costs), so you can compute the exact fee before submitting, with no auctions and no gas-price spikes.
 
 If you have used a metered cloud API, fees will feel familiar: just as an API charges per request and throttles abuse, Cardano charges per transaction by size and complexity, pricing both bandwidth (size) and compute (ExUnits). Collateral works like a pre-authorized hold or security deposit: if your script crashes and consumes node resources, the deposit covers it; if everything succeeds, you keep it.
 
@@ -49,17 +49,19 @@ When a transaction runs Plutus scripts (spending from a script address, minting
 flowchart TD
     A["Transaction size (bytes)"] --> B["Size fee: a * size + b"]
     C["Script execution (CPU + memory)"] --> D["Script fee: cpu*price_cpu + mem*price_mem"]
+    F["Referenced script bytes"] --> G["Ref-script fee: tiered per byte"]
     B --> E["Total fee"]
     D --> E
+    G --> E
 ```
 
 Script costs are measured in **execution units (ExUnits)**: memory units (peak memory) and CPU steps (CPU budget). The script fee is `mem_price * memory_units + step_price * cpu_steps`, added to the size fee. Transaction-building libraries simulate execution to compute ExUnits automatically before submission, see the Evolution SDK's [script evaluation](https://github.com/IntersectMBO/evolution-sdk) for how this works under the hood.
 
 ## Reference script fees
 
-Transactions that use [reference scripts](/docs/developers/curriculum/fundamentals/core-concepts/transactions#reference-inputs-and-reference-scripts) pay a third component: every byte of every script the transaction references is charged, starting at 15 lovelace per byte (the `minFeeRefScriptCostPerByte` parameter, set through governance). The price is tiered: for each successive 25,600-byte increment of total referenced script size, the per-byte price multiplies by 1.2, so referencing a few kilobytes costs a fraction of an ADA while very large reference scripts get progressively expensive. Only the script's own serialized bytes count, not the CBOR wrapping around them.
+Transactions that use [reference scripts](/docs/developers/curriculum/fundamentals/core-concepts/transactions#reference-inputs-and-reference-scripts) pay a third component: every byte of every reference script carried by the transaction's inputs, spent or referenced, used or not, is charged, starting at 15 lovelace per byte (the `minFeeRefScriptCostPerByte` parameter, set through governance). The price is tiered: for each successive 25,600-byte increment of total referenced script size, the per-byte price multiplies by 1.2, so referencing a few kilobytes costs a fraction of an ADA while very large reference scripts get progressively expensive, up to a hard cap of 200 KiB of referenced script per transaction. Only the script bytes themselves count, not the CBOR tag and Plutus version number the ledger wraps around them.
 
-The tiering exists because a referenced script is cheap for the transaction that names it but real work for every node, which must fetch and deserialize it. After that asymmetry was exploited on mainnet in 2024, the pricing moved from linear to escalating: ordinary scripts stay cheap, abuse prices itself out. For a fully worked mainnet example, from raw CBOR to the final lovelace, see the [Cardano Blueprint's transaction fee page](https://cardano-scaling.github.io/cardano-blueprint/ledger/transaction-fee.html).
+The fee exists because a referenced script is cheap for the transaction that names it but real work for every node, which must fetch and deserialize it. Reference scripts were free when Babbage introduced them, and that asymmetry was attacked on mainnet in June 2024; Conway priced them, with an escalating rather than flat rate, so ordinary scripts stay cheap while abuse prices itself out. For a fully worked mainnet example, from raw CBOR to the final lovelace, see the [Cardano Blueprint's transaction fee page](https://cardano-scaling.github.io/cardano-blueprint/ledger/transaction-fee.html).
 
 ## Collateral
 
@@ -75,7 +77,7 @@ Rules:
 - **Consumed only** if phase-2 validation fails.
 - **Collateral return (CIP-40):** since Vasil, a transaction can specify a collateral return address so only the required amount is taken, not the entire UTXO.
 
-Losing collateral is avoidable in practice. Phase-2 validation is deterministic: it depends only on the transaction and the outputs it spends or references, so a script that passed when you evaluated it locally cannot fail on-chain against those same inputs. If the chain changes underneath the transaction, say an input gets spent first, it fails phase 1 instead, which costs nothing. A submitter who validates before submitting should never actually forfeit collateral. The CIP-40 return address exists for the case where you cannot pre-validate because a third party evaluates scripts on your behalf; before it, whatever UTXO you put up as collateral was at risk in its entirety rather than just the required amount.
+Losing collateral is avoidable in practice. Phase-2 validation is deterministic: it depends only on the transaction and the outputs it spends or references, so a script that passed when you evaluated it locally cannot fail on-chain against those same inputs. If the chain changes underneath the transaction, say an input gets spent first, it fails phase 1 instead, which costs nothing. A submitter who validates before submitting should never forfeit collateral. The CIP-40 return address exists for the case where you cannot pre-validate because a third party evaluates scripts on your behalf.
 
 This is the canonical reference for collateral; the [transaction lifecycle](/docs/developers/curriculum/fundamentals/core-concepts/transactions#deterministic-outcomes) and [Smart Contracts](/docs/developers/curriculum/smart-contracts/overview) link here.
 
@@ -92,7 +94,8 @@ It's a real tuning axis, not just theory:
 ## Key takeaways
 
 - Fees are deterministic: `fee = a * size + b`, knowable exactly before submission.
-- Script transactions add an ExUnits-based execution fee on top of the size fee; builders compute it automatically. Reference scripts add a third, per-byte fee that escalates in tiers for very large scripts.
+- Script transactions add an ExUnits-based execution fee on top of the size fee; builders compute it automatically.
+- Reference scripts add a third, per-byte fee that escalates in tiers for very large scripts.
 - Collateral (ADA-only) is forfeited only on phase-2 script failure; CIP-40 returns the excess.
 - Fees are pooled and distributed across block-producing stake pools each epoch.
 

docs/developers/curriculum/fundamentals/core-concepts/transactions.md

@@ -146,7 +146,7 @@ Once a transaction passes submission validation and enters the mempool, it is gu
 ### Latency vs finality
 
 - **Latency**: time to appear in a block (~20s average block time).
-- **Finality**: time to become practically irreversible. Depends on your risk tolerance; most applications treat [10-20 confirmations, a few minutes,](/docs/developers/curriculum/fundamentals/consensus-and-ouroboros#how-does-finality-work) as strong finality, high-value transfers wait longer.
+- **Finality**: time to become practically irreversible. Depends on your risk tolerance; most applications treat [10-20 confirmations](/docs/developers/curriculum/fundamentals/consensus-and-ouroboros#how-does-finality-work) (a few minutes) as strong finality, high-value transfers wait longer.
 
 ## Serialization (CBOR)
 

docs/developers/curriculum/production/transaction-chaining.md

@@ -36,7 +36,7 @@ graph LR
     style B fill:#FFFFFF,stroke:#0033AD,stroke-width:2px,color:#000000
 ```
 
-Under the hood the mempool is an ordered sequence. The node validates each arriving transaction against a recent chain tip (the mempool's *anchor*) plus everything already in the sequence, and order is preserved, so a producing transaction always sits ahead of its spender. When the tip changes, the node revalidates the sequence in order, and a transaction that drops out forces everything after it to be rechecked, because later transactions may have been building on it. That is the mechanical reason a chain lives or dies with its first link: lose it, and every dependent transaction is invalidated in the same sweep. The [Cardano Blueprint's mempool page](https://cardano-scaling.github.io/cardano-blueprint/mempool/index.html) documents this sequence machinery in full.
+Under the hood the mempool is an ordered sequence, validated against a recent ledger state (its *anchor*). In the reference node, a change of tip revalidates the sequence in order, and a transaction that drops out forces everything after it to be rechecked, because later transactions may have been building on it. The ledger only requires that a producing transaction come before its spender; a dependency-aware mempool could recheck less. The [Cardano Blueprint's mempool page](https://cardano-scaling.github.io/cardano-blueprint/mempool/index.html) documents this machinery in full.
 
 Once a transaction is accepted into the mempool it keeps its place [toward inclusion](/docs/developers/curriculum/fundamentals/core-concepts/transactions#the-transaction-lifecycle) for as long as it stays valid against the node's evolving view of the chain. The chain as a whole, though, is only as durable as its first link.
 

docs/developers/curriculum/smart-contracts/advanced/design-patterns/merkelized-validator.md

@@ -17,7 +17,7 @@ script size.
 
 We can take advantage of reference scripts and the withdraw-zero trick to separate the logic (and code) of our validator across a number of stake scripts (which we provide as reference inputs). Then our main validator simply checks for the presence of the associated staking script in the redeemers (and verifies that the redeemer to the scripts are as expected) where necessary to execute the branch of logic.
 
-This is useful because with reference scripts this essentially gives us the ability to create scripts with near infinite size which means optimization strategies that involve increasing script size to reduce mem / CPU (ie loop unrolling) now are available to us at nearly zero cost.
+This is useful because with reference scripts this essentially gives us the ability to create scripts with near infinite size which means optimization strategies that involve increasing script size to reduce mem / CPU (ie loop unrolling) now are available to us. The referenced bytes still pay the [tiered reference script fee](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees), but that is far below carrying the script inline.
 
 Consider a batching architecture, with a very large `processOrders` function. Normally it would not be feasible to perform recursion unrolling / inlining optimizations with such a function since it would quickly exceed the max script size limit; however, with this design pattern we simply move `processOrders` into its own validator script which we can fill with 16kb of loop unrolling and other powerful optimizations which increase script size in order to reduce ExUnits. We provide this new script as a reference script when executing our main validator. Then in our main validator we verify that the `processOrders` validator was executed with the expected redeemer (`input_arg` must match the arguments we want to pass to `processOrders`) after which we have access to the result of the optimized `processOrders` function applied to our inputs.
 
@@ -28,7 +28,7 @@ Since transaction size is limited in Cardano, some scripts benefit from a soluti
 This design pattern offers an interface for off-loading such validations into an external observer/withdrawal script, so that the sizes of the scripts themselves can stay within the limits of Cardano.
 
 :::note
-Be aware that total size of reference scripts is currently limited to 200KiB (204800 bytes), and they also impose additional fees in an exponential manner. See [here](https://github.com/IntersectMBO/cardano-ledger/issues/3952) and [here](https://github.com/CardanoSolutions/ogmios/releases/tag/v6.5.0) for more info.
+Be aware that total size of reference scripts is currently limited to 200KiB (204800 bytes), and they impose [per-byte fees that escalate in tiers](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees).
 :::
 
 ### Key Types

docs/developers/curriculum/smart-contracts/advanced/uplc.md

@@ -88,7 +88,7 @@ This type system allows high-level languages to serialize complex data structure
 
 ### Binary Encoding and Execution
 
-On-chain, UPLC programs are stored as compact binary data using the "flat" encoding format. This binary representation is what validators actually receive and execute. The flat blob is then wrapped in a CBOR byte string, and the script hash that addresses the script on-chain is computed over that wrapper, which is why script bytes sometimes appear double-CBOR-encoded in tooling. The [reference script fee](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees) is metered on the script's own serialized bytes.
+On-chain, UPLC programs are stored as compact binary data using the "flat" encoding format. This binary representation is what validators actually receive and execute. The flat blob is then wrapped in a CBOR byte string, and the script hash that addresses the script on-chain is computed over a one-byte language tag (PlutusV1, V2, or V3) followed by that wrapper. That is why identical bytes hash differently under different Plutus versions, and why script bytes sometimes appear double-CBOR-encoded in tooling. The [reference script fee](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees) is metered on those same wrapped bytes, the language tag aside.
 
 **Size Implications**: UPLC programs can be large, which is why transaction size limits (16KB) become important for complex smart contracts. Recent improvements like reference scripts help mitigate this.
 

docs/developers/curriculum/smart-contracts/overview.md

@@ -146,7 +146,7 @@ A few ledger features shape how you design contracts:
 
 - **Reference inputs ([CIP-31](https://cips.cardano.org/cip/CIP-31))**: read a UTXO's data without spending it, so many contracts can read one oracle feed at once.
 - **Inline datums ([CIP-32](https://cips.cardano.org/cip/CIP-32))**: store the datum in the output itself instead of a hash. See [Datum, redeemer & context](/docs/developers/curriculum/smart-contracts/datum-redeemer-context#datum-hash-vs-inline-datum).
-- **Reference scripts ([CIP-33](https://cips.cardano.org/cip/CIP-33))**: deploy a script once and reference it from later transactions. The transactions shrink; the referenced script pays a smaller [per-byte fee](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees) of its own. See [Lock and spend](/docs/developers/curriculum/smart-contracts/lock-and-spend#reference-scripts).
+- **Reference scripts ([CIP-33](https://cips.cardano.org/cip/CIP-33))**: deploy a script once and reference it from later transactions. The transaction shrinks, and the referenced bytes carry a [per-byte fee](/docs/developers/curriculum/fundamentals/core-concepts/fees#reference-script-fees) well below the cost of inlining. See [Lock and spend](/docs/developers/curriculum/smart-contracts/lock-and-spend#reference-scripts).
 - **Collateral output ([CIP-40](https://cips.cardano.org/cip/CIP-40))**: return excess collateral to an address you choose.
 
 A validator's rules cannot be changed after deployment, and the compiled code cannot be turned back into source.