SimplicityHL getting started

[imaginator]

This is someone's first hands-on with Simplicity. It's also the page we send people before a hackathon to ensure their dev environment is setup and working.

We need a good tutorial at https://github.com/BlockstreamResearch/simplicity-lang-org/edit/main/docs/getting-started/simplicityhl.md

Dev Environment Setup

• Explain required environment (Rust toolchain, Docker images, Bitcoin/Elements/Liquid node).
• Provide installation steps for SimplicityHL compiler and supporting CLI tools.
• Show how to configure the local environment for Liquid testnet/signet (e.g., elementsd setup, funding addresses).
• Verify setup with a minimal “compile and inspect contract” example.

Writing a Contract

• Provide a walkthrough of a simple but meaningful contract (e.g., “only spendable after block height X” or a 2-of-2 multisig).

Testing and Weight Analysis

• Explain how to measure contract weight and resource cost (e.g., command-line tools or analysis reports).

Broadcasting to Liquid

• Explain how to take the compiled Simplicity contract, produce its Taproot commitment, create a transaction that locks Liquid funds to that commitment, and broadcast that transaction so the contract is live on-chain.
• Document interaction with Elements RPC (or CLI) for broadcasting.
• Provide examples of a successful contract deployment on Liquid testnet/signet. (maybe include https://liquid.network/ link to observe)

Monitoring Execution and Spending

• Explain how to track contract outputs on the Liquid network.
• Show how to query mempool and block confirmations.
• Document how to observe a contract spend: what gets revealed (script path, contract bitcode) and how to verify correctness.
• Provide guidance on tools/block explorers useful for monitoring.

Debugging and Failure Analysis

Document common errors:

• Invalid compilation / type mismatch.
• Excessive contract weight.
• Incorrect Taproot commitment.
• Transaction rejected by mempool.

Provide step-by-step debugging strategies:

• Inspecting contract bitcode.
• Checking sighash and signature validity.
• Tracing contract evaluation failures.
• Include troubleshooting examples for failed broadcasts and rejected spends.

[imaginator]

Tutorial from @apoelstra

Ok, this is the tutorial as written:

 #!/usr/bin/env bash
 
 set -eou pipefail
 
 # FIXME put title here
 
 #########################
 # 0. Boilerplate to make the tutorial executable as a script
 #
 # Skip ahead to step 1 if you are reading
 #########################
 
 DEFAULT_ELEMENTSD=elementsd
 DEFAULT_SIMC=simc
 DEFAULT_HAL_SIMPLICITY=hal_simplicity
 
 : "${TUTORIAL_ELEMENTSD:=$DEFAULT_ELEMENTSD}"
 : "${TUTORIAL_SIMC:=$DEFAULT_SIMC}"
 : "${TUTORIAL_HAL_SIMPLICITY:=$DEFAULT_HAL_SIMPLICITY}"
 
 FAIL=no
 if ! command -v "$TUTORIAL_ELEMENTSD"; then
     echo "Could not execute elementsd (path: $TUTORIAL_ELEMENTSD)" >&2
     echo "To override this path, set the TUTORIAL_ELEMENTSD environment variable." >&2
     echo  >&2
     echo "elementsd may be obtainable from your package manager, or from https://github.com/ElementsProject/elements/releases" >&2
     FAIL=yes
 fi
 if ! command -v "$TUTORIAL_SIMC"; then
     if [ "$FAIL" = "yes" ]; then echo >&2; fi
     echo "Could not execute simc (path: $TUTORIAL_SIMC)" >&2
     echo "To override this path, set the TUTORIAL_SIMC environment variable." >&2
     echo  >&2
     echo "simc can be installed with 'cargo install simc', or from https://github.com/BlockstreamResearch/SimplicityHL" >&2
     FAIL=yes
 fi
 if ! command -v "$TUTORIAL_HAL_SIMPLICITY"; then
     if [ "$FAIL" = "yes" ]; then echo >&2; fi
     echo "Could not execute hal-simplicity (path: $TUTORIAL_HAL_SIMPLICITY)" >&2
     echo "To override this path, set the TUTORIAL_HAL_SIMPLICITY environment variable." >&2
     echo  >&2
     echo "simc can be installed with 'cargo install hal-simplicity', or from https://github.com/BlockstreamResearch/hal-simplicity" >&2
     FAIL=yes
 fi
 
 [ "$FAIL" = "yes" ] && exit 1
 
 #########################
 # 1. Generate a fresh keypair.
 #########################
 
 KEYPAIR_JSON=$("$TUTORIAL_HAL_SIMPLICITY" simplicity keypair generate)
 SECRET_HEX=$(echo "$KEYPAIR_JSON" | jq -r .secret)
 PUBLIC_HEX=$(echo "$KEYPAIR_JSON" | jq -r .x_only)
 
 echo "Using keypair $KEYPAIR_JSON"
 
 #########################
 # 2. Create a SimplicityHL program which uses the keypair.
 #########################
 
 # FIXME use tmpfile and a trap to clean up
 cat > temp-program.temp <<EOF
 fn main() {
     let pubkey: u256 = 0x${PUBLIC_HEX};
 
     jet::bip_0340_verify((pubkey, jet::sig_all_hash()), witness::SIGNATURE)
 }
 EOF
 
 PROGRAM_B64=$("$TUTORIAL_SIMC" temp-program.temp)
 
 # FIXME should probably remove this stutter
 "$TUTORIAL_HAL_SIMPLICITY" simplicity simplicity info "$PROGRAM_B64"

It looks like I was using simc and parameterizing a SimplicityHL (using shell variable interpolation) by a fresh keypair. The next step, I think, would be to extract the address from hal-simplicity simplicity simplicity info at the end and to send coins to it (I think, we need to copy the existing elements asset tutorial in spinning up a fresh regtest node)

[iajhff]

here's some guide i generated and scripts i used to deploy regtest and testnet locally https://github.com/iajhff/simplicitybasics i created this to contribute to your documentation and for my own learning

[imaginator]

this is absolutely fantastic. Having a good walkthough to broadcast a TX to the mempool is great. I love your debug area too!

[imaginator]

dropping this here for reference: https://pastecode.io/s/fa4qzyb5

[schoen]

I'm going to close this as we've had quickstarts up for some time. #28 is still open and I'm still working on that (now pursuing the plan to switch the main/recommended quickstart to something using Rust, as being more realistic for how people are developing SimplicityHL applications).