Functions for retrieving information from output_null_datum

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Added
+- Extended functions for retrieving information from `OP_RETURN`.
+
+### Changed
 - Bumped Simplex to 0.2.0.
 - Aligned existing testing API with changes in Simplex.
 

README.md

@@ -48,21 +48,21 @@ simf/lib
 │   │   │   └── Functions for asserting `AssetId` in inputs and outputs.
 │   │   └── asset_id_with_amount.simf
 │   │       └── Functions for asserting `Amount` and `AssetId` in inputs and outputs.
-│   └── getters
-│       ├── amount.simf
-│       │   └── Functions for retrieving `Amount` in inputs and outputs.
-│       ├── asset_id.simf
-│       │   └── Functions for retrieving `AssetId` in inputs and outputs.
-│       ├── asset_id_with_amount.simf
-│       │   └── Functions for retrieving `Amount` and `AssetId` in inputs and outputs.
-│       └── script_hash.simf
-│           └── Functions for retrieving hash of the scriptPubKey in inputs and outputs.
+│   ├── getters
+│   │   ├── amount.simf
+│   │   │   └── Functions for retrieving `Amount` in inputs and outputs.
+│   │   ├── asset_id.simf
+│   │   │   └── Functions for retrieving `AssetId` in inputs and outputs.
+│   │   ├── asset_id_with_amount.simf
+│   │   │   └── Functions for retrieving `Amount` and `AssetId` in inputs and outputs.
+│   │   └── script_hash.simf
+│   │       └── Functions for retrieving hash of the scriptPubKey in inputs and outputs.
+│   └── op_return.simf
+│       └── Utilities for detecting and enforcing `OP_RETURN` (null data) outputs.
 ├── asserts.simf
 │   └── Assertion helpers: `assert_eq_*` for uints and `bool`, plus `assert_none_*` for `Option`.
-├── binary.simf
-│   └── Basic binary logic operations: `and`, `or`, `not`, `xor`.
-└── op_return.simf
-    └── Utilities for detecting and enforcing `OP_RETURN` (null data) outputs.
+└── binary.simf
+    └── Basic binary logic operations: `and`, `or`, `not`, `xor`.
 ```
 
 ## Installation

docs/stdlib.json

@@ -489,20 +489,90 @@
     "output_type": "bool",
     "description": "Return the logical XOR of the two given values."
   },
+  {
+    "simplicityhl_name": "get_entry_option",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "Option<OpReturnEntry>",
+    "description": "Return specified entry at the given OP_RETURN output and given index. Return `None` if the output doesn't exist, isn't null data, or has no such entry."
+  },
+  {
+    "simplicityhl_name": "pushed_data_from_entry",
+    "section": "OP_RETURN",
+    "input_type": "OpReturnEntry",
+    "output_type": "Option<(u2, u256)>",
+    "description": "Return `(x, hash)` from the given entry if it is pushed data and `None` otherwise. `hash` is the SHA256 hash of the pushed data and `x` indicates how the data was pushed: 0 is an immediate 0 to 75 bytes, 1 is an OP_PUSHDATA1, 2 is an OP_PUSHDATA2 and 3 is an OP_PUSHDATA4."
+  },
+  {
+    "simplicityhl_name": "get_pushed_data",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "Option<(u2, u256)>",
+    "description": "Return `(x, hash)` if the entry at the given index of the given output is pushed data. `hash` is the SHA256 hash of the pushed data and `x` indicates how the data was pushed: 0 is an immediate 0 to 75 bytes, 1 is an OP_PUSHDATA1, 2 is an OP_PUSHDATA2 and 3 is an OP_PUSHDATA4."
+  },
+  {
+    "simplicityhl_name": "op_x_minus_1_from_entry",
+    "section": "OP_RETURN",
+    "input_type": "OpReturnEntry",
+    "output_type": "Option<u4>",
+    "description": "Return `x - 1` from the given entry if it is OP_x for x in the range 1..=16 and `None` otherwise."
+  },
+  {
+    "simplicityhl_name": "get_op_x_minus_1",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "Option<u4>",
+    "description": "Return `x - 1` if the given entry at the given output is OP_x for x in the range 1..=16 and `None` otherwise."
+  },
+  {
+    "simplicityhl_name": "negate_or_reserved_from_entry",
+    "section": "OP_RETURN",
+    "input_type": "OpReturnEntry",
+    "output_type": "Option<u1>",
+    "description": "Return `Some(0)` if the given entry is OP_1NEGATE, `Some(1)` if the entry is OP_RESERVED and `None` otherwise."
+  },
+  {
+    "simplicityhl_name": "get_negate_or_reserved",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "Option<u1>",
+    "description": "Return `Some(0)` if the the entry at the given entry of the given output is OP_1NEGATE, `Some(1)` if the entry is OP_RESERVED and `None` otherwise."
+  },
+  {
+    "simplicityhl_name": "kind_of_entry",
+    "section": "OP_RETURN",
+    "input_type": "OpReturnEntry",
+    "output_type": "u8",
+    "description": "Return the kind of the entry. 0 is pushed data, 1 is OP_1..OP_16 and 2 is OP_1NEGATE or OP_RESERVED."
+  },
   {
     "simplicityhl_name": "is_output_op_return",
     "section": "OP_RETURN",
     "input_type": "u32",
     "output_type": "bool",
     "description": "Return `true` if the output at the given index is an OP_RETURN (null data) output, `false` otherwise (including if the output does not exist)."
   },
+  {
+    "simplicityhl_name": "has_entry",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "bool",
+    "description": "Return true if the given output is an OP_RETURN output that has an entry at `entry_index`."
+  },
   {
     "simplicityhl_name": "assert_output_is_op_return",
     "section": "OP_RETURN",
     "input_type": "u32",
     "output_type": "()",
     "description": "Assert that the output at the given index is an OP_RETURN (null data) output.\n\n## Panics\nThe assertion fails."
   },
+  {
+    "simplicityhl_name": "assert_has_entry",
+    "section": "OP_RETURN",
+    "input_type": "u32, u32",
+    "output_type": "()",
+    "description": "Assert that the given output is an OP_RETURN that has an entry at `entry_index`.\n\n## Panics\nThe assertion fails."
+  },
   {
     "simplicityhl_name": "ge_to_point",
     "section": "secp256k1 operations",

simf/lib/utxo/op_return.simf

@@ -0,0 +1,119 @@
+pub type OpReturnEntry = Either<(u2, u256), Either<u1, u4>>;
+
+/// Returns specified entry at the specified OP_RETURN output and entry index.
+/// Returns `None` if the output doesn't exist, isn't null data, or has no such entry.
+pub fn get_entry_option(output_index: u32, entry_index: u32) -> Option<OpReturnEntry> {
+    match jet::output_null_datum(output_index, entry_index) {
+        Some(entry_option: Option<OpReturnEntry>) => entry_option,
+        None => None,
+    }
+}
+
+/// Returns `(x, hash)` from the specified entry if it is pushed data and `None` otherwise.
+/// 
+/// `hash` is the SHA256 hash of the pushed data and `x` indicates how the data was pushed:
+/// 
+/// 0 is an immediate 0 to 75 bytes, 1 is an OP_PUSHDATA1,
+/// 2 is an OP_PUSHDATA2 and 3 is an OP_PUSHDATA4.
+pub fn pushed_data_from_entry(entry: OpReturnEntry) -> Option<(u2, u256)> {
+    match entry {
+        Left(pushed_data: (u2, u256)) => Some(pushed_data),
+        Right(_other: Either<u1, u4>) => None,
+    }
+}
+
+/// Returns `(x, hash)` if the the entry at entry_index of the specified output is pushed data.
+/// 
+/// `hash` is the SHA256 hash of the pushed data and `x` indicates how the data was pushed:
+/// 
+/// 0 is an immediate 0 to 75 bytes, 1 is an OP_PUSHDATA1,
+/// 2 is an OP_PUSHDATA2 and 3 is an OP_PUSHDATA4.
+pub fn get_pushed_data(output_index: u32, entry_index: u32) -> Option<(u2, u256)> {
+    let entry: Option<OpReturnEntry> = get_entry_option(output_index, entry_index);
+
+    match entry {
+        Some(entry: OpReturnEntry) => pushed_data_from_entry(entry),
+        None => None,
+    }
+}
+
+/// Returns `x - 1` from the specified entry if it is `OP_x` for x in the range 1..=16 and `None` otherwise
+pub fn op_x_minus_1_from_entry(entry: OpReturnEntry) -> Option<u4> {
+    match entry {
+        Left(_pushed_data: (u2, u256)) => None,
+        Right(right: Either<u1, u4>) => match right {
+            Left(_negate_or_reserved: u1) => None,
+            Right(op_x_minus_1: u4) => Some(op_x_minus_1),
+        },
+    }
+}
+
+/// Returns `x - 1` if the specified entry at the specified output is `OP_x` for x in the range 1..=16 and `None` otherwise
+pub fn get_op_x_minus_1(output_index: u32, entry_index: u32) -> Option<u4> {
+    let entry: Option<OpReturnEntry> = get_entry_option(output_index, entry_index);
+
+    match entry {
+        Some(entry: OpReturnEntry) => op_x_minus_1_from_entry(entry),
+        None => None,
+    }
+}
+
+/// Returns Some(0) if the specified entry is OP_1NEGATE, Some(1) if the entry is OP_RESERVED and `None` otherwise
+pub fn negate_or_reserved_from_entry(entry: OpReturnEntry) -> Option<u1> {
+    match entry {
+        Left(_pushed_data: (u2, u256)) => None,
+        Right(right: Either<u1, u4>) => match right {
+            Left(negate_or_reserved: u1) => Some(negate_or_reserved),
+            Right(_op_x_minus_1: u4) => None,
+        },
+    }
+}
+
+/// Returns Some(0) if the the entry at entry_index of the specified output is OP_1NEGATE,
+/// Some(1) if the entry is OP_RESERVED and `None` otherwise
+pub fn get_negate_or_reserved(output_index: u32, entry_index: u32) -> Option<u1> {
+    let entry: Option<OpReturnEntry> = get_entry_option(output_index, entry_index);
+
+    match entry {
+        Some(entry: OpReturnEntry) => negate_or_reserved_from_entry(entry),
+        None => None,
+    }
+}
+
+/// Returns the kind of the entry.
+/// 0 is pushed data, 1 is OP_1..OP_16 and 2 is OP_1NEGATE or OP_RESERVED
+pub fn kind_of_entry(entry: OpReturnEntry) -> u8 {
+    match entry {
+        Left(_pushed_data: (u2, u256)) => 0,
+        Right(right_branch: Either<u1, u4>) => match right_branch {
+            Left(_negate_or_reserved: u1) => 2,
+            Right(_op_x_minus_1: u4) => 1,
+        },
+    }
+}
+
+/// Returns true if the specified output is an OP_RETURN (null data) output.
+pub fn is_output_op_return(output_index: u32) -> bool {
+    match jet::output_null_datum(output_index, 0) {
+        Some(_entry_option: Option<OpReturnEntry>) => true,
+        None => false,
+    }
+}
+
+/// Returns true if the specified output is an OP_RETURN output that has an entry at entry_index
+pub fn has_entry(output_index: u32, entry_index: u32) -> bool {
+    match get_entry_option(output_index, entry_index) {
+        Some(_entry: OpReturnEntry) => true,
+        None => false,
+    }
+}
+
+/// Asserts that the specified output is an OP_RETURN (null data) output
+pub fn assert_output_is_op_return(output_index: u32) {
+    assert!(is_output_op_return(output_index));
+}
+
+/// Asserts that the specified output is an OP_RETURN output that has an entry at entry_index
+pub fn assert_has_entry(output_index: u32, entry_index: u32) {
+    assert!(has_entry(output_index, entry_index));
+}