jets.md.py

#!/usr/bin/env python3

# This consumes elements.json as generated by
# https://github.com/BlockstreamResearch/SimplicityHL/tree/master/codegen
# and generates doc/documentation/jets.md.

import datetime
import json
import re
import sys

preamble = """<!-- Generated from {} by jets.md.py on {} -->
# Jets reference

Simplicity jets are built-in functions which you can call to efficiently perform various computations, including some related to arithmetic, logic, and cryptography.

## Uses of jets

Jet calls are currently used in SimplicityHL to perform many operations, such as integer comparisons or arithmetic, that have dedicated notation in other programming languages.

* For example, in SimplicityHL, you check whether two integers are equal with a call to a jet such as `jet::eq_32`.

Some jets allow a Simplicity program to refuse a proposed transaction by performing a mandatory assertion (these jets' return type is `()` below). The "panic" or failure effect produced by these jets is the *only* way to decline a transaction, so every program will need to call one or more of these jets directly or indirectly.

* For example, `jet::bip_0340_verify` checks a digital signature and refuses the transaction if the signature cannot be verified.

Jets also provide information about the currently proposed transaction, enabling [introspection](../glossary.md#introspection) of its inputs and outputs.

* For example, `jet::output_script_hash` provides the cryptographic identity of the program that controls a specified output of the proposed transaction. This can be used to require that assets are sent back to a copy of a specific [program](../glossary.md#program) (a [covenant](../glossary.md#covenant)).

## Jet list

Here is a complete list of the available jets in the Elements Simplicity integration available on Liquid Network, their <a href="../../simplicityhl-reference/type/">type signatures</a>, and a description of what they do.
""".format(sys.argv[1], datetime.datetime.now().date().isoformat())

print(preamble)

def new_section(section_name, introduction = ""):
    template = """
### {}

{}

???+ "Click to hide"
    | <div style="width:22em">Jet</div> | Description |
    | ----------------------------------- | ----------- |"""
    return template.format(section_name, introduction)

elements = json.load(open(sys.argv[1]))

def format_jet(name, i, o, desc):
    return "    | `{}({}) -> {}` | {} |".format(name, i, o, desc)

section = ""
for jet in elements:
    jet["description"] = re.sub("\\n", "<br>", jet["description"])
    if "deprecated" in jet and jet["deprecated"]:
        continue
    this_section = jet["section"]
    if this_section != section:
        print(new_section(this_section))
        section = this_section
    print(format_jet(jet["simplicityhl_name"], jet["input_type"], jet["output_type"], jet["description"]))

# Remove a level of section nesting from the special Deprecated jets section
print(re.sub("^#", "", new_section("Deprecated jets", "Four jets related to time locks have been deprecated."), flags=re.MULTILINE))

for jet in elements:
    if "deprecated" in jet and jet["deprecated"]:
        print(format_jet(jet["simplicityhl_name"], jet["input_type"], jet["output_type"], jet["description"]))

footer = """
These jets' names may have been changed in some tools and libraries to discourage their use.

## Notation

There are three styles of writing jet names that you may encounter in Simplicity-related tooling or source code.

* SimplicityHL writes jets like `jet::eq_32`.
* Disassembly of low-level Simplicity writes them like `jet_eq_32`.
* Rust source code writes them like `Elements::Eq32`.

The reference list above is aimed at SimplicityHL developers, so it presents jet names in SimplicityHL format. Remember to include `jet::` before the name of the jet when calling it from a SimplicityHL program.

## More about jet implementation

The list of jets is fixed when Simplicity is integrated with a specific blockchain, because their details become part of the consensus rules for each Simplicity-enabled blockchain. A complete list of jets must be predefined so different verifiers can agree on what a particular Simplicity program means and what its exact behavior is when it is run. Jet implementations are available in native code to allow miners and other node operators to run these functions more quickly and efficiently.

Calling jets, where available, makes your Simplicity program smaller and faster.

A few jets <a href="https://delvingbitcoin.org/t/delving-simplicity-part-two-side-effects/2091">provide behaviors that could not be achieved directly with low-level Simplicity combinators alone</a>, such as transaction introspection. Jets that can fail (those whose return type is `()`) are the expected and only way for a Simplicity program to disapprove a proposed transaction."""

print(footer)