Beersy
BRC-15

Bitcoin Script Assembly Language

Bitcoin's scripting instructions are numbers, which machines read easily and people do not. This defines a readable way to write them down, so a developer can inspect a script and reason about what it does.

Ty Everett3 min read
basm sourceopcodes hex

Summary

Why
Bitcoin script opcodes are machine-readable but not human-readable, making them hard to write, review, or debug by hand.
What
BRC-15 defines a human-readable assembly language, with a .basm file extension, for writing Bitcoin scripts as text that assembles down to opcodes.
How
A developer writes opcodes in uppercase without the OP_ prefix, marks pushed data as strings, hex, or <template> variables, splits unlocking and locking code with .unlock and .lock, and an assembler strips comments and whitespace, fills in template values, and converts everything to the final hex-encoded opcode string.

What this lets you do

  • Write Bitcoin scripts as readable text instead of raw hex
  • Mark unlocking vs sections with .unlock and .lock
  • Use <template> placeholders for values filled in later
  • Comment scripts inline with # for future readers
  • Assemble a .basm file into a fully compiled opcode string

Written by claude-sonnet-5 from the specification text. Where the two differ, the original is correct.

Reference for an AI

Everything an assistant needs to answer questions about BRC-15 accurately, including what it depends on.

The specification

Read the original

Abstract

Bitcoin script is a programming language used in Bitcoin transactions to control the spending of coins. While the Bitcoin script opcodes are machine-readable, they are not easily human-readable. We define an assembly language that provides a human-readable format for expressing Bitcoin script opcodes, making it easier for developers to understand and write Bitcoin scripts. This specification defines the rules for expressing Bitcoin script opcodes in assembly format, including indentation, comments, expressing text strings and numbers, templating and other guidelines.

Motivation

Bitcoin script is a powerful tool for controlling the spending of coins, but its opcodes can be difficult for developers to read and understand. By providing a human-readable assembly format for expressing Bitcoin script opcodes, developers can more easily write and debug Bitcoin scripts. This specification aims to standardize the assembly format for Bitcoin script opcodes, making it easier for developers to work with Bitcoin transactions.

This specification is intended to start the discussion and propose an initial format for representing Bitcoin scripts in an assembly language. Iterative improvement through future BRCs will help improve this standard.

Specification

We specify an assembly language for Bitcoin script programs as follows:

Syntax

  • Opcodes should be expressed in uppercase and without OP_ prefixing, e.g. CHECKSIG.
  • Data to push on the stack is represented by strings, hex values, or template variables.
  • Whitespace should be used for indentation and to separate tokens.
  • Comments should start with the # character and extend to the end of the line.
  • .unlock and .lock can be used to denote the boundary between an and its corresponding lock.

For example:

.unlock
  <sig> # The signature used to unlock the script
  <key> # The public key that unlocks the script

.lock
  DUP HASH160 # Duplicate the key and take its hash
  1a98d1ea5702a518b8c4ad9bb736bf34fa9e7291 EQUALVERIFY # Check the hashes are equal
  CHECKSIG # Check that the signature from this key is valid

Data types

  • Numeric values should be expressed as their corresponding opcodes, or in hexadecimal format.
  • String values should be enclosed in single quotes.
  • Hex values should be expressed in lowercase, without 0x prefixing.
  • Template variables are placed in angle brackets like <hash>

For example:

OVER 3 SPLIT NIP TRUE SPLIT SWAP SPLIT DROP HASH160 <hash> EQUALVERIFY CHECKSIG

Flow control

Conditional statements should use the IF opcode, followed by the conditional expression and the ELSE or ENDIF opcodes.

For example:

2 3 ADD 5 EQUAL IF # if 2 + 3 = 5
  'yes' RETURN     # Return 'yes'
ELSE               # Otherwise
  'no' RETURN      # Return 'no'
ENDIF              # End

File Extension

We specify that .basm files can be used to represent Bitcoin assembly language programs.

Implementation

The process of assembling programs written in this assembly language comprises:

  • Obtaining the values for template variables, either programmatically or by seeking user input
  • Substituting template variable placeholders for the actual values
  • Removing comments
  • Computing and adding the correct PUSHDATA opcodes for adding string and hexadecimal values to the stack
  • Converting all string values to hexadecimal
  • Substituting all opcode names for their hexadecimal coded values
  • Removing .unlock and .lock annotations if present
  • Removing all whitespace to arrive at the fully-assembled program
Was this helpful?

Search Beersy

Search standards by number, title, author or topic