repository·master·Indexed 43 days ago
https://github.com/intersectmbo/cardano-ledgerFormal specifications, executable models, and implementations of the Cardano Ledger across multiple eras, including Byron, Shelley, Allegra, Mary, Alonzo, Babbage, and Conway. Includes validation rules for blocks and transactions, cryptographic primitives via cardano-crypto-wrapper, and tools for managing LedgerState and UTXO sets.
The cardano-ledger package provides the implementation of the validation rules for the Cardano Ledger. These rules define the state transition systems used to:
This implementation is based on the formal specification defined in the main cardano-ledger repository.
The cardano-crypto-wrapper provides the core cryptographic primitives used within the Cardano ledger. It abstracts several critical security functions:
cryptonite library.ByteStrings.To/FromCBOR instances (compatible with the cardano-ledger-binary package) for all cryptographic data types to ensure consistent binary encoding/decoding.A token bundle is a heterogeneous collection of tokens and is the standard, and only, way to represent and store assets on the Cardano blockchain.
Key characteristics:
{ MyAddress, TB_Example }).Note: While token bundles handle multi-asset amounts, certain transaction fields like the fee field must still explicitly specify ada amounts.
{
NFLPlayerCardsPolicyID {
(SomeNFLPlayerCard, 1),
(SomeOtherNFLPlayerCard, 1),
(YetAnotherNFLPlayerCard, 1)}
RushConcertPolicyID {
(Tickets, 500),
(VIPTickets, 50)}
}Cardano's native tokens differ significantly from Ethereum's ERC20 standard because their tracking and accounting are built directly into the Cardano ledger.
Key Advantages of Native Tokens:
| Feature | ERC20 | Native tokens |
| :--- | :--- | :--- |
| Blockchain | Ethereum | Cardano |
| Relationship to the blockchain | A contract standard, users copy-paste the standard code and modify it. | Not a standard. Most functionality is built into the ledger itself. |
| Controlled by | A Solidity smart contract | A minting policy script in any scripting language supported by Cardano |
| Requires a smart contract to mint/burn? | Y | Y |
| Minting logic can be customized? | Y | Y |
| Requires a smart contract to transfer? | Y | N |
| Can be used by other smart contracts without special support? | N | Y |
| Can be transferred alongside other tokens? | N | Y |
| Transfer logic provided by | Copy-pasting from the ERC20 template | The Cardano ledger itself |
| Transfer logic can be customized | Y | N |
| Requires special fees to transfer | Y | N |
| Requires additional event-handling logic to track transfers | Y | N |
| Supports non-fungible tokens | N | Y |
| Readable metadata | Provided by the operating smart contract | Provided by the off-chain metadata server |The Chain Quality property ensures the integrity and quality of the chain structure.
Theorem 7 (Chain quality): In a $\Delta$-semisynchronous environment, the probability that an $\alpha$-dominated adversary $A$ causes the protocol $\pi_{SPoS}$ to violate the chain quality property (with parameters $k$ and $\mu = 1/k$) over $R$ slots is no more than $\exp(\ln R - \Omega(k))$.
The Common Prefix property ensures that there is a low probability of different parts of the network seeing different versions of the chain history.
Theorem 5 (Common prefix): In a $\Delta$-semisynchronous environment, the probability that an $\alpha$-dominated adversary $A$ causes the protocol $\pi_{SPoS}$ to violate the common prefix property with parameter $k$ over $R$ slots is no more than $\exp(\ln R + \Delta - \Omega(k))$.
When designing token systems on Cardano, it is important to understand how native tokens differ from ERC20 smart contract tokens in terms of security and implementation.
Native tokens are handled directly by the Cardano ledger, which eliminates several common vulnerabilities found in ERC20 implementations:
Note on Denial of Service: While native tokens mitigate many smart contract-specific risks, they do not eliminate the possibility of system-wide denial of service attacks via gas price manipulation.
In the Conway era, using Reference Scripts in a transaction incurs an additional fee to prevent DDoS attacks involving large, expensive-to-deserialize scripts. Instead of a simple linear cost, the protocol uses a tiered pricing mechanism.
To calculate the total size used for the fee:
Key Calculation Rules:
25KiB (25,600 bytes) chunks. Each subsequent chunk is more expensive than the previous one by a multiplier of 1.2.tierRefScriptFee :: Integer -> Integer
tierRefScriptFee = go 0 minFeeRefScriptCostPerByte
where
go acc curTierPrice n
| n < sizeIncrement =
floor (acc + (n % 1) * curTierPrice)
| otherwise =
let acc' = acc + curTierPrice * (sizeIncrement % 1)
in go acc' (multiplier * curTierPrice) (n - sizeIncrement)
sizeIncrement = 25600
multiplier = 1.2
minFeeRefScriptCostPerByte = 15To prevent transaction outputs from becoming so large that they cannot be spent without exceeding the maximum transaction size, the ledger enforces a constraint on the size of the token bundle in transaction outputs.
Unlike the min-ada-value calculation which uses an estimated size, this constraint uses the actual size of the serialized representation of the token bundle.
The constraint is governed by the protocol parameter maxValSize.
Current Value:
maxValSize = 4000 bytes (equivalent to 500 words).To prevent network splitting during hard forks, the Cardano ledger uses versioned serialization schemes instead of static ToCBOR and FromCBOR typeclasses.
Previously, fixing a deserialization bug required maintaining two separate serializations for the same type simultaneously, which was difficult to manage with the standard FromCBOR typeclass. The new approach introduces a typeclass that depends on both the type and the protocol version (or the ledger era).
When implementing or using serializers, you must now provide the appropriate protocol version or ledger era to ensure the correct serialization logic is applied for the current network state.
A minting policy is a set of rules that regulates the creation and destruction of assets scoped under it. The ledger checks adherence to these rules whenever a transaction attempts to use the mint field.
Key types of policies include:
The Cardano Ledger has transitioned from tracking deposit amounts via global protocol parameters to tracking individual deposits.
Previously, deposit amounts for stake credential registrations and stake pool registrations were determined by protocol parameters. If these parameters changed:
To prevent economic exploits (like registering credentials right before a deposit increase) and to avoid 'split-brain' states during hard forks, the ledger now tracks the specific amount paid by each individual. When a user de-registers a resource, the ledger pays back exactly what they originally deposited.