DOCSEARCHbyAlgolia
Submit Docs

Pebble Documentation

website·Indexed 32 days ago

https://pluts.harmoniclabs.tech

Documentation for Pebble 0.3.1, a language for writing on-chain smart contracts on Cardano. Includes guides on the UTxO model, validators, compiler configuration, and a comprehensive standard library covering types like Array<T>, LinearMap<K, V>, and cryptographic functions in std.crypto.

Tokens
31.8K
Snippets
188
Records
257
Agent score
58%

What's inside Pebble

  1. Overview of the Pebble language

    Pebble is a strongly-typed domain-specific language (DSL) used to write Cardano smart contracts. It is a functional language with an imperative bias that targets UPLC (Plutus Core). It provides a statement-oriented syntax (using constructs like let, if, while, match, and return) to make it feel familiar to developers experienced with JavaScript, TypeScript, Rust, or Solidity, while maintaining the strict guarantees of Plutus Core.

  2. Overview of LinearMap<K, V>

    LinearMap<K, V> is an association list used as Cardano's on-chain map. It is structurally a List<LinearMapEntry<K, V>> consisting of (K, V) pairs. Lookups have O(n) time complexity. It is used primarily because it matches the underlying Plutus representation used by the blockchain.
    const m: LinearMap<bytes, int> = { #01: 10, #02: 20 };

match m.lookup(#01) {
    Some{ value: amount }: trace(amount),
    None{}: fail "missing"
}

  3. Overview of std.crypto.bls12_381

    The std.crypto.bls12_381 namespace provides operations for the BLS12-381 pairing-friendly curve. This is used for implementing zero-knowledge proofs, BLS signatures, and other protocols requiring efficient on-chain bilinear pairings. The native types G1, G2, and MlResult are exported exclusively through this namespace and must be fully qualified or brought into scope using the using keyword.

  4. Overview of std.linearMap

    std.linearMap provides polymorphic helpers for LinearMap<K, V>, which is an ordered list of (K, V) pairs used as an association list in Cardano's on-chain representation. Lookups have O(n) time complexity. Because this representation is what Plutus uses, it is preferred over hash maps in this context. All functions in this module are also available as methods on the LinearMap<K, V> type.

  5. Overview of List<T>

    List<T> is a singly-linked list of elements of type T that maps to Plutus Core's built-in list. It supports standard list operations and can be initialized using array-like literal syntax.
    const empty: List<int> = [];
const xs: List<int>    = [1, 2, 3];

  6. Understand the Plutus Core `data` type

    The data type is a serialization format used at the system boundary for datums, redeemers, and script contexts. Every on-chain type can be encoded into and decoded from data. While the compiler typically handles this via the .toData() method or pattern-matching, raw data is used when manually constructing or inspecting CBOR shapes.

  7. Use arbitrary-precision integers with the `int` type

    The int type represents an arbitrary-precision signed integer. It maps directly to Plutus Core's Integer and does not overflow. It supports decimal literals, hexadecimal literals (prefixed with 0x), and underscores as cosmetic separators for readability.
    const supply: int = 1_000_000;
let spent: int = 500;

const left = supply - spent;
assert left >= 0 else "underflow";

  8. Understand Pebble validator fundamentals

    A validator in Pebble is a function (context) -> void | fail executed by the Cardano ledger during events like spending a UTxO or minting a token. If the function completes without failing, the action is allowed; otherwise, it is rejected. In Pebble, developers define a contract declaration, and the compiler synthesizes the underlying validator function from the defined methods.

  9. Understand the Cardano UTxO model

    Cardano uses an Unspent Transaction Output (UTxO) model where the ledger is a set of UTxOs. There is no global account balance; a user's balance is the sum of all UTxOs they can spend. A transaction consumes existing UTxOs (inputs) and produces new ones (outputs).

  10. Use the string type for logging and error messages

    The string type represents UTF-8 text and maps to Plutus Core String. It is primarily intended for logging via trace and for fail messages. Because every character consumes CPU and memory from the script budget, avoid storing large strings on-chain.
    const msg: string = "Order filled";
trace(msg);

  11. Distinguish between Datums and Redeemers in Pebble

    In the context of Cardano and Pebble, Datums and Redeemers serve different roles:

    ConceptLocationSet ByTimingPebble Mapping
    DatumUTxO (output)Output creatorCreation timestate fields or raw data in OutputDatum
    RedeemerAction (spend/mint)Transaction submitterAction attemptMethod arguments

    Datums represent per-UTxO state, while redeemers represent the intent of the specific action being attempted.

  12. Use std.boolean for higher-order boolean operations

    The std.boolean module provides monomorphic helpers over bool. While standard operators (&&, ||, !) are preferred for regular code, these functions are intended for partial application and higher-order use (e.g., passing a boolean operation as an argument to a fold or map function).
    const signs: List<boolean> = [true, true, true, false];

// Using std.boolean.strictAnd as a reducer in foldl
const allPositive: boolean = std.list.foldl(std.boolean.strictAnd, true, signs);
assert !allPositive else "expected one false";