Merge pull request #12 from apoelstra/2025-10/gettingstarted

Improvements to "getting started" guide

Author: imaginator

docs/documentation/how-simplicity-works.md

@@ -5,7 +5,7 @@ Simplicity is a typed, combinator-based, functional smart contract language with
 Frequently used operations are implemented as jets. Jets are predefined, highly efficient building blocks, allowing contracts to execute complex conditional payments, options, and multi-party transactions with predictable resource usage and no reliance on a central authority.
 
 Let's delve deeper into how Simplicity works within the Bitcoin ecosystem:
- 
+
 ## SimplicityHL Compilation and Simplicity Bytecode
 
 SimplicityHL is a developer-friendly front-end language, engineered to simplify the process of writing smart contracts by offering a syntax akin to the Rust programming language. It effectively abstracts away the intricate, low-level functional programming details inherent in raw Simplicity. The SimplicityHL Compiler is the dedicated toolchain responsible for translating SimplicityHL code into its foundational Simplicity representation. This approach is crucial because, while Simplicity offers profound mathematical expressiveness, its low-level nature means that practically, developers will write in higher-level languages that then compile down to Simplicity, complete with formal proofs of their correct operation.
@@ -41,21 +41,16 @@ Jets are optimised native code implementations that act as "shortcuts" for large
 Examples of jets include:
 
 - **Cryptographic functions**: These are crucial for secure smart contracts. Specific examples include the SHA-256 compression function and Schnorr signature verification (BIP-340). Other elliptic curve functions for `secp256k1` are also included, such as point verification, scalar arithmetic, and field element operations.
-
 - **Arithmetic operations**: Simplicity includes jets for various arithmetic functions, such as 32-bit addition, subtraction, and multiplication. General multi-bit logic operations like `complement`, `and`, `or`, and `xor` are also implemented as jets.
-
 - **Introspection operations**: These allow smart contracts to examine transaction data. Examples include `script-cmr` (script commitment Merkle root), `internal-key`, `version`, `lock-time`, `output-value`, `input-value`, `tapleaf-version`, and `tappath`.
-
 - **Time locks**: Jets exist for various time-based conditions like `check-lock-height`, `check-lock-time`, `tx-height-lock`, `tx-time-lock`, `tx-distance-lock`, and `tx-duration-lock`, which assert conditions based on block height or time.
-
 - **Elements-specific jets**: For the Liquid Network, Simplicity includes additional jets related to Elements features such as issuances, assets, amounts, range proofs, and surjection proofs.
 
 The weight of a Simplicity program, including its jets, is calculated using static analysis before execution from the number of iterations needed to execute the program on the Bit Machine. If this weight is larger than the on-chain footprint of the program, the program must be padded to meet the weight. This means that blockchain validators and transactors continue to have one metric for a transaction's cost: the weight of the transaction, even though the computational cost to validators is not a direct function of this weight. This crucial feature enables users to determine the maximum computational resources (CPU time and memory) a program will require, even for worst-case scenarios. This pre-computation capability is a fundamental defence against denial-of-service attacks, as transactions with excessively costly scripts can be rejected early.
 
 Simplicity employs a fine-grained cost function that allows for precisely calibrated fees based on the actual resources consumed, balancing affordability for legitimate use with disincentives for network abuse. There are two categories of jets:
 
 1. **Ordinary jets**: Handled locally by implementations.
-
 2. **Discounted jets**: These receive special treatment under consensus rules, with explicitly defined cost overrides that are determined through benchmarking, rather than being calculated solely by the Bit Machine's default rules.
 
 This mechanism ensures that highly efficient native code implementations (jets) are correctly accounted for, making complex smart contracts economically viable and predictable for Bitcoin's robust, long-term infrastructure. Simplicity thus empowers builders with unprecedented security and flexibility, solidifying Bitcoin's role as a foundation for a resilient, censorship-resistant financial future.

docs/documentation/jets-explained.md

@@ -7,19 +7,15 @@ This process accelerates computation without changing the underlying meaning, wh
 Think of a Jet as a shortcut:
 
 - Without Jets: Simplicity executes everything step by step using combinators (correct but slow).
-
 - With Jets: the same logic runs much faster, but the result is **provably identical**.
 
 ---
 
 ## Why are Jets Important?
 
 - **Performance**: Blockchain validation must be fast. Jets dramatically reduce computation time.
-
 - **Security**: Each Jet is rigorously specified and formally proven to behave exactly like its Simplicity equivalent.
-
 - **Consensus Safety**: Jets have fixed, predictable costs to prevent denial-of-service attacks.
-
 - **Scalability**: More complex smart contracts become feasible without compromising verification speed.
 
 ## Jet Creation Process

docs/documentation/jets-overview.md

@@ -6,40 +6,47 @@ Jets are available for common bit widths: **1, 8, 16, 32, 64, 128, 256**. Operat
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`add_N`** - Addition with carry flag
+
 - `(uN, uN) → (bool, uN)`
 - `let (carry, sum) = jet::add_32(x, y);`
 
-### Subtraction Operations  
+### Subtraction Operations
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`subtract_N`** - Subtraction with borrow flag
+
 - `(uN, uN) → (bool, uN)`
 
 ### Multiplication Operations
 **Available bit widths:** 8, 16, 32, 64, 128
 
 **`multiply_N`** - Multiplication returning double-width result
+
 - `(uN, uN) → u(2N)`
 
 ### Division Operations
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`divide_N`** - Division returning quotient and remainder
+
 - `(uN, uN) → (uN, uN)`
 
 ### Increment/Decrement Operations
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`increment_N`** / **`decrement_N`** - Add/subtract 1 with overflow flag
+
 - `uN → (bool, uN)`
 
 ## Comparison Jets
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`eq_N`**, **`le_N`**, **`lt_N`** - Equality and comparison operations
+
 - `(uN, uN) → bool`
 
 **`max_N`**, **`min_N`** - Return larger/smaller value
+
 - `(uN, uN) → uN`
 
 ## Bitwise Integer Operations
@@ -48,20 +55,24 @@ Jets are available for common bit widths: **1, 8, 16, 32, 64, 128, 256**. Operat
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`and_N`**, **`or_N`**, **`xor_N`** - Bitwise logical operations
+
 - `(uN, uN) → uN`
 
 **`complement_N`** - Bitwise NOT
+
 - `uN → uN`
 
 ### Bit Shifting Operations
 **Available bit widths:** 1, 8, 16, 32, 64, 128, 256
 
 **`shift_left_N`**, **`shift_right_N`** - Bit shifting
+
 - `(uN, u8) → uN`
 
 ## Type Conversion Jets
 
 **`left_pad_low_A_B`** - Zero-pad smaller type to larger type
+
 - `uA → uB` (e.g., `u16 → u32`)
 - Example: `jet::left_pad_low_16_32(x)`
 
@@ -74,26 +85,33 @@ Jets are available for common bit widths: **1, 8, 16, 32, 64, 128, 256**. Operat
 ### Hash Functions
 
 **`sha_256_ctx_8_init`** - Initialize SHA-256 context
+
 - `() → Ctx8`
 
 **`sha_256_ctx_8_add_4`** - Add 4-byte word to SHA-256 context
+
 - `(Ctx8, u32) → Ctx8`
 
 **`sha_256_ctx_8_finalize`** - Finalize SHA-256 hash
+
 - `Ctx8 → u256`
 
 ### Digital Signatures
 
 **`bip_0340_check`** - Verify BIP-340 Schnorr signature (returns bool)
+
 - `(Pubkey, u256, Signature) → bool`
 
 **`bip_0340_verify`** - Verify BIP-340 Schnorr signature (panics if invalid)
+
 - `((Pubkey, u256), Signature) → ()`
 
 ## Bitcoin-Specific Jets
 
 **`sig_all_hash`** - Compute SIGHASH_ALL signature hash
+
 - `() → u256`
 
 **`check_lock_height`** - Validate height-based timelock
-- `u32 → ()`
+
+- `u32 → ()`

docs/getting-started/cli.md

@@ -5,6 +5,7 @@
 This guide shows the complete command-line workflow for developing and deploying Simplicity contracts using `simply` and `elements-cli`.
 
 **Tools used:**
+
 - `simply` - SimplicityHL development toolkit
 - `elements-cli` - Liquid node client
 - `curl` - API requests to Liquid testnet
@@ -115,10 +116,12 @@ simply withdraw --entrypoint always_true.simf --txid c2f44551601034af3cc0d004b5b
 ```
 
 Replace:
+
 - `<txid>` - From step 4
 - `<destination>` - Where to send funds
 
 **What this does:**
+
 - Fetches UTXO from blockchain
 - Builds complete transaction
 - Encodes Simplicity program and witness
@@ -214,6 +217,7 @@ let sighash = tx_env.c_tx_env().sighash_all();
 ```
 
 **Sighash includes:**
+
 - All transaction inputs and outputs
 - Genesis hash (network identifier)
 - Spent UTXO data
@@ -247,8 +251,9 @@ You would need to:
 3. Your private key
 
 **Signing options:**
+
 - Liquid wallet with signing capabilities
-- Hardware wallet with Schnorr support  
+- Hardware wallet with Schnorr support
 - Software cryptographic libraries
 - External signing services
 
@@ -412,6 +417,7 @@ simply run --entrypoint contract.simf --logging debug
 ```
 
 **Shows execution trace:**
+
 - Each step
 - Jet calls
 - Debug output
@@ -431,6 +437,7 @@ simply build --entrypoint contract.simf --stats
 ```
 
 **Shows:**
+
 - Cost bounds
 - Memory usage
 - Program size
@@ -457,6 +464,7 @@ https://blockstream.info/liquidtestnet/api
 ```
 
 **Endpoints:**
+
 - `/address/<address>/utxo` - Get UTXOs
 - `/tx/<txid>` - Get transaction
 - `/tx/<txid>/status` - Check confirmation