diff --git a/CHANGELOG.md b/CHANGELOG.md index eaf6170..20e7693 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## [Unreleased] +## [0.0.2] - Added `mul_div` functions. - Organized code into modules. @@ -11,7 +11,7 @@ ## [0.0.1] Initial release! -- Сhecked arithmetic operations for `u8`, `u16`, `u32`, `u64`, and `u128`. +- Сhecked arithmetic operations for `u8`, `u16`, `u32`, `u64`, `u128` and `u256`. - `OP_RETURN` detection utilities. - Implementation of `and`, `or`, `not`, and `xor` binary operators. - Basic numeric assertions. diff --git a/README.md b/README.md index d77c4a0..074f198 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,10 @@ simf/lib ├── u64 │ ├── convert.simf │ │ └── Conversions between `u8`, `u16`, `u32`, `u64` and other uint types. -│ └── math.simf -│ └── Overflow-checked arithmetic and `gt`/`ge` functions. +│ ├── math.simf +│ │ └── Overflow-checked arithmetic and `gt`/`ge` functions. +│ └── mul_div.simf +│ └── Full-precision calculation of `floor(a * b / denominator)`. ├── u128 ├── u256 │ ├── bit.simf @@ -34,8 +36,25 @@ simf/lib │ │ └── Basic comparison operations available as jets for `u8`-`u64` but missing for `u128` and `u256`. │ ├── convert.simf │ │ └── Conversions between `u128`, `u256` and other uint types. -│ └── math.simf -│ └── Carry/borrow arithmetic, multiplication, division, and overflow-checked wrappers. +│ ├── math.simf +│ │ └── Carry/borrow arithmetic, multiplication, division, and overflow-checked wrappers. +│ └── mul_div.simf +│ └── Full-precision calculation of `floor(a * b / denominator)`. +├── utxo +│ ├── asserts +│ │ ├── amount.simf +│ │ │ └── Functions for asserting `Amount` in inputs and outputs. +│ │ ├── asset_id.simf +│ │ │ └── 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. ├── asserts.simf │ └── Assertion helpers: `assert_eq_*` for uints and `bool`, plus `assert_none_*` for `Option`. ├── binary.simf diff --git a/docs/stdlib.json b/docs/stdlib.json index ad2e2cc..1c7e670 100644 --- a/docs/stdlib.json +++ b/docs/stdlib.json @@ -109,168 +109,168 @@ "section": "Amount asserts", "input_type": "u32, bool, u64", "output_type": "()", - "description": "Asserts that the explicit amount at the specified input or output index equals the expected u64 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit amount at the specified input or output index equals the expected `u64` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_amount", "section": "Amount asserts", "input_type": "u32, bool, Confidential1", "output_type": "()", - "description": "Asserts that the confidential amount at the specified input or output index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential amount at the specified input or output index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_input_amount", "section": "Amount asserts", "input_type": "u32, u64", "output_type": "()", - "description": "Asserts that the explicit amount at the specified input index equals the expected u64 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit amount at the specified input index equals the expected `u64` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_input_amount", "section": "Amount asserts", "input_type": "u32, Confidential1", "output_type": "()", - "description": "Asserts that the confidential amount at the specified input index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential amount at the specified input index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_output_amount", "section": "Amount asserts", "input_type": "u32, u64", "output_type": "()", - "description": "Asserts that the explicit amount at the specified output index equals the expected u64 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit amount at the specified output index equals the expected `u64` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_output_amount", "section": "Amount asserts", "input_type": "u32, Confidential1", "output_type": "()", - "description": "Asserts that the confidential amount at the specified output index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential amount at the specified output index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_current_amount", "section": "Amount asserts", "input_type": "u64", "output_type": "()", - "description": "Asserts that the explicit input amount at the current_index equals the expected u64 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit input amount at the current_index equals the expected `u64` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_current_amount", "section": "Amount asserts", "input_type": "Confidential1", "output_type": "()", - "description": "Asserts that the confidential input amount at the current_index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential input amount at the current_index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, bool, u256, u64", "output_type": "()", - "description": "Asserts that explicit asset_id and amount at the specified input or output index equal the expected u256 and u64 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that explicit asset_id and amount at the specified input or output index equal the expected `u256` and `u64` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, bool, Confidential1, Confidential1", "output_type": "()", - "description": "Asserts that confidential asset_id and amount at the specified input or output index equal the expected Confidential1 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that confidential asset_id and amount at the specified input or output index equal the expected `Confidential1` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_input_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, u256, u64", "output_type": "()", - "description": "Asserts that explicit asset_id and amount at the specified input index equal the expected u256 and u64 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that explicit asset_id and amount at the specified input index equal the expected `u256` and `u64` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_input_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, Confidential1, Confidential1", "output_type": "()", - "description": "Asserts that confidential asset_id and amount at the specified input index equal the expected Confidential1 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that confidential asset_id and amount at the specified input index equal the expected `Confidential1` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_output_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, u256, u64", "output_type": "()", - "description": "Asserts that explicit asset_id and amount at the specified output index equal the expected u256 and u64 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that explicit asset_id and amount at the specified output index equal the expected `u256` and `u64` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_output_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u32, Confidential1, Confidential1", "output_type": "()", - "description": "Asserts that confidential asset_id and amount at the specified output index equal the expected Confidential1 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that confidential asset_id and amount at the specified output index equal the expected `Confidential1` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_current_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "u256, u64", "output_type": "()", - "description": "Asserts that explicit input asset_id and amount at the current_index equal the expected u256 and u64 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that explicit input asset_id and amount at the current_index equal the expected `u256` and `u64` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_current_asset_id_with_amount", "section": "AssetId and Amount asserts", "input_type": "Confidential1, Confidential1", "output_type": "()", - "description": "Asserts that confidential input asset_id and amount at the current_index equal the expected Confidential1 values.\n\n## Panics\nThe assertion fails." + "description": "Asserts that confidential input asset_id and amount at the current_index equal the expected `Confidential1` values.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_asset_id", "section": "AssetId asserts", "input_type": "u32, bool, u256", "output_type": "()", - "description": "Asserts that the explicit asset_id at the specified input or output index equals the expected u256 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit asset_id at the specified input or output index equals the expected `u256` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_asset_id", "section": "AssetId asserts", "input_type": "u32, bool, Confidential1", "output_type": "()", - "description": "Asserts that the confidential asset_id at the specified input or output index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential asset_id at the specified input or output index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_input_asset_id", "section": "AssetId asserts", "input_type": "u32, u256", "output_type": "()", - "description": "Asserts that the explicit asset_id at the specified input index equals the expected u256 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit asset_id at the specified input index equals the expected `u256` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_input_asset_id", "section": "AssetId asserts", "input_type": "u32, Confidential1", "output_type": "()", - "description": "Asserts that the confidential asset_id at the specified input index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential asset_id at the specified input index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_output_asset_id", "section": "AssetId asserts", "input_type": "u32, u256", "output_type": "()", - "description": "Asserts that the explicit asset_id at the specified output index equals the expected u256 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit asset_id at the specified output index equals the expected `u256` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_output_asset_id", "section": "AssetId asserts", "input_type": "u32, Confidential1", "output_type": "()", - "description": "Asserts that the confidential asset_id at the specified output index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential asset_id at the specified output index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_explicit_current_asset_id", "section": "AssetId asserts", "input_type": "u256", "output_type": "()", - "description": "Asserts that the explicit input asset_id at the current_index equals the expected u256 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the explicit input asset_id at the current_index equals the expected `u256` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "assert_confidential_current_asset_id", "section": "AssetId asserts", "input_type": "Confidential1", "output_type": "()", - "description": "Asserts that the confidential input asset_id at the current_index equals the expected Confidential1 value.\n\n## Panics\nThe assertion fails." + "description": "Asserts that the confidential input asset_id at the current_index equals the expected `Confidential1` value.\n\n## Panics\nThe assertion fails." }, { "simplicityhl_name": "get_explicit_amount", @@ -732,7 +732,7 @@ "section": "`u8` arithmetic", "input_type": "u8, u8, u8", "output_type": "u8", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u8 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u8` or if the denominator is zero." }, { "simplicityhl_name": "u8_to_u16", @@ -858,7 +858,7 @@ "section": "`u16` arithmetic", "input_type": "u16, u16, u16", "output_type": "u16", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u16 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u16` or if the denominator is zero." }, { "simplicityhl_name": "u16_to_u32", @@ -984,7 +984,7 @@ "section": "`u32` arithmetic", "input_type": "u32, u32, u32", "output_type": "u32", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u32 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u32` or if the denominator is zero." }, { "simplicityhl_name": "u32_to_u64", @@ -1117,7 +1117,7 @@ "section": "`u64` arithmetic", "input_type": "u64, u64, u64", "output_type": "u64", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u64 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u64` or if the denominator is zero." }, { "simplicityhl_name": "u64_to_u128", @@ -1320,7 +1320,7 @@ "section": "`u128` arithmetic", "input_type": "u128, u128, u128", "output_type": "u128", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u128 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u128` or if the denominator is zero." }, { "simplicityhl_name": "and_128", @@ -1481,7 +1481,7 @@ "section": "`u256` arithmetic", "input_type": "bool, u256, u256", "output_type": "(bool, u256)", - "description": "Add two u256 values, taking an incoming carry bit. Return the outgoing carry bit and the sum." + "description": "Add two `u256` values, taking an incoming carry bit. Return the outgoing carry bit and the sum." }, { "simplicityhl_name": "checked_add_256", @@ -1578,7 +1578,7 @@ "simplicityhl_name": "div_mod_256_64", "section": "`u256` arithmetic", "input_type": "u256, u64", - "output_type": "()", + "output_type": "(u256, u64)", "description": "Divide a `u256` value by a `u64` value, returning the `u256` quotient and the `u64` remainder.\n\n## Panics\nPanics if the divisor is zero." }, { @@ -1621,7 +1621,7 @@ "section": "`u256` arithmetic", "input_type": "u256, u256, u256", "output_type": "u256", - "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a u256 or if the denominator is zero." + "description": "Calculate `floor(a * b / denominator)` with full precision. \n\n## Panics\nPanics if the result overflows a `u256` or if the denominator is zero." }, { "simplicityhl_name": "and_256", diff --git a/simf/lib/asserts.simf b/simf/lib/asserts.simf index 1c6ad58..6ab2638 100644 --- a/simf/lib/asserts.simf +++ b/simf/lib/asserts.simf @@ -1,6 +1,6 @@ use crate::lib::u128::bit::eq_128; -/// Asserts that two `u1` are equal +/// Asserts that two u1 are equal pub fn assert_eq_1(a: u1, b: u1) { assert!(jet::eq_1(a, b)) } diff --git a/simf/lib/u16/math.simf b/simf/lib/u16/math.simf index ce298c8..ccdb49d 100644 --- a/simf/lib/u16/math.simf +++ b/simf/lib/u16/math.simf @@ -53,7 +53,7 @@ pub fn checked_div_16(a: u16, b: u16) -> Option { } } -/// Returns the quotient of two u16 values, panics if the result overflows u16 +/// Returns the quotient of two u16 values, panics if the divisor is zero pub fn div_16(a: u16, b: u16) -> u16 { unwrap(checked_div_16(a, b)) } diff --git a/simf/lib/u256/math.simf b/simf/lib/u256/math.simf index 8750b2f..3102eea 100644 --- a/simf/lib/u256/math.simf +++ b/simf/lib/u256/math.simf @@ -280,7 +280,7 @@ fn normalize_to_threshold_256_63(a: u256, b: u128, is_b_u128: bool) -> (u64, u25 /// the most significant non-zero word of `b` is at least 2^127. /// /// The normalized dividend fits into 384 bits and is returned as a -/// `(u128, u256)` pair. The normalized divisor fits into a `u256`. +/// `(u128, u256)` pair. The normalized divisor fits into a u256. fn normalize_to_threshold_256_127(a: u256, b: u256) -> (u128, u256, u256) { let norm: u128 = calculate_normalizer_base_128(b); diff --git a/simf/lib/u256/mul_div.simf b/simf/lib/u256/mul_div.simf index f4f9878..73a3efa 100644 --- a/simf/lib/u256/mul_div.simf +++ b/simf/lib/u256/mul_div.simf @@ -94,7 +94,7 @@ fn estimate_quotient_digit_base_128(u2: u128, u1: u128, u0: u128, v1: u128, v0: /// the most significant non-zero word of `b` is at least 2^127. /// /// The normalized dividend fits into 640 bits and is returned as a -/// `(u128, u256, u256)` tuple. The normalized divisor fits into a `u256` +/// `(u128, u256, u256)` tuple. The normalized divisor fits into a u256 fn normalize_to_threshold_512_127(a_high: u256, a_low: u256, b: u256) -> (u128, u256, u256, u256) { let norm: u128 = calculate_normalizer_base_128(b); @@ -125,10 +125,10 @@ fn mul_and_sub_128(q: u128, u2: u128, u1: u128, u0: u128, v: u256) -> (u128, u12 split_u256_into_u128(u_updated_1_0) } -/// Divides a 512-bit integer by a 256-bit integer and returns a `u256` quotient. +/// Divides a 512-bit integer by a 256-bit integer and returns a u256 quotient. /// Implements Algorithm D by Donald Knuth. /// Requires the upper half of the divisor to be non-zero (`divisor >= 2^128`) -/// and the quotient to fit into `u256` +/// and the quotient to fit into u256 fn algorithm_d_512_256(dividend_high: u256, dividend_low: u256, divisor: u256) -> u256 { let ( _, diff --git a/simf/lib/u32/math.simf b/simf/lib/u32/math.simf index 0253b5e..a7d6417 100644 --- a/simf/lib/u32/math.simf +++ b/simf/lib/u32/math.simf @@ -53,7 +53,7 @@ pub fn checked_div_32(a: u32, b: u32) -> Option { } } -/// Returns the quotient of two u32 values, panics if the result overflows u32 +/// Returns the quotient of two u32 values, panics if the divisor is zero pub fn div_32(a: u32, b: u32) -> u32 { unwrap(checked_div_32(a, b)) } diff --git a/simf/lib/u64/math.simf b/simf/lib/u64/math.simf index 05a8498..93c11eb 100644 --- a/simf/lib/u64/math.simf +++ b/simf/lib/u64/math.simf @@ -53,7 +53,7 @@ pub fn checked_div_64(a: u64, b: u64) -> Option { } } -/// Returns the quotient of two u64 values, panics if the result overflows u64 +/// Returns the quotient of two u64 values, panics if the divisor is zero pub fn div_64(a: u64, b: u64) -> u64 { unwrap(checked_div_64(a, b)) } diff --git a/simf/lib/u8/math.simf b/simf/lib/u8/math.simf index 1e56ee6..b942cd1 100644 --- a/simf/lib/u8/math.simf +++ b/simf/lib/u8/math.simf @@ -53,7 +53,7 @@ pub fn checked_div_8(a: u8, b: u8) -> Option { } } -/// Returns the quotient of two u8 values, panics if the result overflows u8 +/// Returns the quotient of two u8 values, panics if the divisor is zero pub fn div_8(a: u8, b: u8) -> u8 { unwrap(checked_div_8(a, b)) } diff --git a/simf/lib/utxo/getters/amount.simf b/simf/lib/utxo/getters/amount.simf index 55c2f75..4901fe0 100644 --- a/simf/lib/utxo/getters/amount.simf +++ b/simf/lib/utxo/getters/amount.simf @@ -6,9 +6,10 @@ /// in unnecessary overhead. /// Returns the explicit amount at the specified input or output. +/// Panics if the specified input or output does not exist or if its amount is confidential. /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection -/// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. +/// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly pub fn get_explicit_amount(index: u32, is_input_index: bool) -> u64 { let ( _, @@ -21,10 +22,11 @@ pub fn get_explicit_amount(index: u32, is_input_index: bool) -> u64 { unwrap_right::<(u1, u256)>(amount) } -/// Returns the confidential amount at the specified input or output +/// Returns the confidential amount at the specified input or output. +/// Panics if the specified input or output does not exist or if its amount is explicit. /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection -/// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. +/// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly pub fn get_confidential_amount(index: u32, is_input_index: bool) -> Confidential1 { let ( _, @@ -37,42 +39,48 @@ pub fn get_confidential_amount(index: u32, is_input_index: bool) -> Confidential unwrap_left::(amount) } -/// Returns the explicit amount at the specified input +/// Returns the explicit amount at the specified input. +/// Panics if the specified input does not exist or if its amount is confidential pub fn get_explicit_input_amount(index: u32) -> u64 { let (_, amount): (Asset1, Amount1) = unwrap(jet::input_amount(index)); unwrap_right::<(u1, u256)>(amount) } -/// Returns the confidential amount at the specified input +/// Returns the confidential amount at the specified input. +/// Panics if the specified input does not exist or if its amount is explicit pub fn get_confidential_input_amount(index: u32) -> Confidential1 { let (_, amount): (Asset1, Amount1) = unwrap(jet::input_amount(index)); unwrap_left::(amount) } -/// Returns the explicit amount at the specified output +/// Returns the explicit amount at the specified output. +/// Panics if the specified output does not exist or if its amount is confidential pub fn get_explicit_output_amount(index: u32) -> u64 { let (_, amount): (Asset1, Amount1) = unwrap(jet::output_amount(index)); unwrap_right::<(u1, u256)>(amount) } -/// Returns the confidential amount at the specified output +/// Returns the confidential amount at the specified output. +/// Panics if the specified output does not exist or if its amount is explicit pub fn get_confidential_output_amount(index: u32) -> Confidential1 { let (_, amount): (Asset1, Amount1) = unwrap(jet::output_amount(index)); unwrap_left::(amount) } -/// Returns the explicit input amount at the current_index +/// Returns the explicit input amount at the current_index. +/// Panics if amount is confidential pub fn get_explicit_current_amount() -> u64 { let (_, amount): (Asset1, Amount1) = jet::current_amount(); unwrap_right::<(u1, u256)>(amount) } -/// Returns the confidential input amount at the current_index +/// Returns the confidential input amount at the current_index. +/// Panics if amount is explicit pub fn get_confidential_current_amount() -> Confidential1 { let (_, amount): (Asset1, Amount1) = jet::current_amount(); diff --git a/simf/lib/utxo/getters/asset_id.simf b/simf/lib/utxo/getters/asset_id.simf index 3e2b8f1..b172992 100644 --- a/simf/lib/utxo/getters/asset_id.simf +++ b/simf/lib/utxo/getters/asset_id.simf @@ -1,6 +1,7 @@ /// Functions for retrieving AssetId -/// Returns the explicit asset_id at the specified input or output +/// Returns the explicit asset_id at the specified input or output. +/// Panics if the specified input or output does not exist or if its asset_id is confidential. /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection /// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. @@ -13,7 +14,8 @@ pub fn get_explicit_asset_id(index: u32, is_input_index: bool) -> u256 { unwrap_right::<(u1, u256)>(asset) } -/// Returns the confidential asset_id at the specified input or output +/// Returns the confidential asset_id at the specified input or output. +/// Panics if the specified input or output does not exist or if its asset_id is explicit /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection /// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. @@ -26,42 +28,48 @@ pub fn get_confidential_asset_id(index: u32, is_input_index: bool) -> Confidenti unwrap_left::(asset) } -/// Returns the explicit asset_id at the specified input +/// Returns the explicit asset_id at the specified input. +/// Panics if the specified input does not exist or if its asset_id is confidential pub fn get_explicit_input_asset_id(index: u32) -> u256 { let asset: Asset1 = unwrap(jet::input_asset(index)); unwrap_right::<(u1, u256)>(asset) } -/// Returns the confidential asset_id at the specified input +/// Returns the confidential asset_id at the specified input. +/// Panics if the specified input does not exist or if its asset_id is explicit pub fn get_confidential_input_asset_id(index: u32) -> Confidential1 { let asset: Asset1 = unwrap(jet::input_asset(index)); unwrap_left::(asset) } -/// Returns the explicit asset_id at the specified output +/// Returns the explicit asset_id at the specified output. +/// Panics if the specified output does not exist or if its asset_id is confidential pub fn get_explicit_output_asset_id(index: u32) -> u256 { let asset: Asset1 = unwrap(jet::output_asset(index)); unwrap_right::<(u1, u256)>(asset) } -/// Returns the confidential asset_id at the specified output +/// Returns the confidential asset_id at the specified output. +/// Panics if the specified output does not exist or if its asset_id is explicit pub fn get_confidential_output_asset_id(index: u32) -> Confidential1 { let asset: Asset1 = unwrap(jet::output_asset(index)); unwrap_left::(asset) } -/// Returns the explicit input asset_id at the current_index +/// Returns the explicit input asset_id at the current_index. +/// Panics if asset_id is confidential pub fn get_explicit_current_asset_id() -> u256 { let asset: Asset1 = jet::current_asset(); unwrap_right::<(u1, u256)>(asset) } -/// Returns the confidential input asset_id at the current_index +/// Returns the confidential input asset_id at the current_index. +/// Panics if asset_id is explicit pub fn get_confidential_current_asset_id() -> Confidential1 { let asset: Asset1 = jet::current_asset(); diff --git a/simf/lib/utxo/getters/asset_id_with_amount.simf b/simf/lib/utxo/getters/asset_id_with_amount.simf index d555e6d..df6d141 100644 --- a/simf/lib/utxo/getters/asset_id_with_amount.simf +++ b/simf/lib/utxo/getters/asset_id_with_amount.simf @@ -1,6 +1,7 @@ /// Functions for retrieving an `AssetId` along with an `Amount` /// Returns explicit asset_id and amount at the specified input or output. +/// Panics if the specified input or output does not exist or if its asset_id and amount are confidential. /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection /// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. @@ -16,7 +17,8 @@ pub fn get_explicit_asset_id_with_amount(index: u32, is_input_index: bool) -> (u (unwrap_right::<(u1, u256)>(asset), unwrap_right::<(u1, u256)>(amount)) } -/// Returns confidential asset_id and amount at the specified input or output +/// Returns confidential asset_id and amount at the specified input or output. +/// Panics if the specified input or output does not exist or if its asset_id and amount are explicit. /// /// Warning: using this incurs the overhead, and should be used only when the input/output selection /// needs to be determined at runtime; otherwise, use the input- or output- specific getter directly. @@ -35,42 +37,48 @@ pub fn get_confidential_asset_id_with_amount( (unwrap_left::(asset), unwrap_left::(amount)) } -/// Returns explicit asset_id and amount at the specified input +/// Returns explicit asset_id and amount at the specified input. +/// Panics if the specified input does not exist or if its asset_id and amount are confidential pub fn get_explicit_input_asset_id_with_amount(index: u32) -> (u256, u64) { let (asset, amount): (Asset1, Amount1) = unwrap(jet::input_amount(index)); (unwrap_right::<(u1, u256)>(asset), unwrap_right::<(u1, u256)>(amount)) } -/// Returns confidential asset_id and amount at the specified input +/// Returns confidential asset_id and amount at the specified input. +/// Panics if the specified input does not exist or if its asset_id and amount are explicit pub fn get_confidential_input_asset_id_with_amount(index: u32) -> (Confidential1, Confidential1) { let (asset, amount): (Asset1, Amount1) = unwrap(jet::input_amount(index)); (unwrap_left::(asset), unwrap_left::(amount)) } -/// Returns explicit asset_id and amount at the specified output +/// Returns explicit asset_id and amount at the specified output. +/// Panics if the specified output does not exist or if its asset_id and amount are confidential pub fn get_explicit_output_asset_id_with_amount(index: u32) -> (u256, u64) { let (asset, amount): (Asset1, Amount1) = unwrap(jet::output_amount(index)); (unwrap_right::<(u1, u256)>(asset), unwrap_right::<(u1, u256)>(amount)) } -/// Returns confidential asset_id and amount at the specified output +/// Returns confidential asset_id and amount at the specified output. +/// Panics if the specified output does not exist or if its asset_id and amount are explicit pub fn get_confidential_output_asset_id_with_amount(index: u32) -> (Confidential1, Confidential1) { let (asset, amount): (Asset1, Amount1) = unwrap(jet::output_amount(index)); (unwrap_left::(asset), unwrap_left::(amount)) } -/// Returns explicit input asset_id and amount at the current_index +/// Returns explicit input asset_id and amount at the current_index. +/// Panics if asset_id and amount are confidential pub fn get_explicit_current_asset_id_with_amount() -> (u256, u64) { let (asset, amount): (Asset1, Amount1) = jet::current_amount(); (unwrap_right::<(u1, u256)>(asset), unwrap_right::<(u1, u256)>(amount)) } -/// Returns confidential input asset_id and amount at the current_index +/// Returns confidential input asset_id and amount at the current_index. +/// Panics if asset_id and amount are explicit pub fn get_confidential_current_asset_id_with_amount() -> (Confidential1, Confidential1) { let (asset, amount): (Asset1, Amount1) = jet::current_amount();