### FromIterator Implementation Examples

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Examples showing how Result implements FromIterator to collect results, stopping at the first error.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Copy Result Contents

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Examples of copying the contents of an Ok variant from a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Clone Result Contents

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Examples of cloning the contents of an Ok variant from a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### BlsSignatureBasic Implementations

Source: https://docs.rs/blsful/4.0.0/blsful/trait.BlsSignatureBasic.html

Examples of DST constant definitions for specific BLS implementations.

```rust
impl BlsSignatureBasic for Bls12381G1Impl {
    const DST: &'static [u8] = b"BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_";
}
```

```rust
impl BlsSignatureBasic for Bls12381G2Impl {
    const DST: &'static [u8] = b"BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_";
}
```

--------------------------------

### Construct a Scalar from uniform bytes

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/trait.FromUniformBytes.html

Example demonstrating the use of BLAKE2b hash output to generate a Scalar via FromUniformBytes.

```rust
use blake2b_simd::blake2b;
use bls12_381::Scalar;
use ff::FromUniformBytes;

// `bls12_381::Scalar` implements `FromUniformBytes<64>`, and BLAKE2b (by default)
// produces a 64-byte hash.
let hash = blake2b(b"Some message");
let val = Scalar::from_uniform_bytes(hash.as_array());
```

--------------------------------

### IntoIterator Implementation Example

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Demonstrates converting a Result into an iterator that yields the contained value if Ok.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

--------------------------------

### Transpose Result and Option

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### Constructing Group Encodings Generically

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/trait.GroupEncoding.html

Example of how to construct a byte representation generically using the Default trait bound.

```rust
let mut encoding = <G as GroupEncoding>::Repr::default();
encoding.as_mut().copy_from_slice(buf);
```

--------------------------------

### Check Result Status

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Examples of checking if a Result is Ok or Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Flatten Nested Results

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Validate Result with Predicate

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Example of using is_ok_and to validate the value inside an Ok variant.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Chain fallible operations with and_then

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Use and_then to sequence operations that return a Result. The second example demonstrates handling file system metadata errors.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### CloneToUninit Implementation

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Experimental nightly-only API for performing copy-assignment to uninitialized memory.

```rust
impl<T> CloneToUninit for T
where T: Clone,
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Create a New BitArray

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/type.FieldBits.html

Initialize a new BitArray from an existing buffer.

```rust
use bitvec::prelude::*;

let data = [0u16, 1, 2, 3];
let bits = BitArray::<_, Msb0>::new(data);
assert_eq!(bits.len(), 64);
```

--------------------------------

### pub fn pairing(p: &G1Affine, q: &G2Affine) -> Gt

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/fn.pairing.html

Computes the pairing of two points without precomputation or optimizations.

```APIDOC
## pairing

### Description
Invoke the pairing function without the use of precomputation and other optimizations.

### Signature
`pub fn pairing(p: &G1Affine, q: &G2Affine) -> Gt`

### Parameters
- **p** (&G1Affine) - A reference to a point on the G1 curve.
- **q** (&G2Affine) - A reference to a point on the G2 curve.

### Returns
- **Gt** - The result of the pairing operation.
```

--------------------------------

### Conversion Implementations

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Provides generic conversion methods using From and Into traits.

```rust
impl<T> Conv for T
fn conv<T>(self) -> T
where Self: Into<T>,
```

```rust
impl<T> From<T> for T
fn from(t: T) -> T
```

```rust
impl<T, U> Into<U> for T
where U: From<T>,
fn into(self) -> U
```

--------------------------------

### verify

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ElGamalProof.html

Verifies the proof and ciphertext using the provided public key.

```APIDOC
## pub fn verify(&self, pk: &PublicKey<C>) -> BlsResult<()>

### Description
Verifies the proof and ciphertext with a public key.

### Parameters
- **pk** (&PublicKey<C>) - Required - The public key used for verification.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the proof is valid, or a BlsError if verification fails.
```

--------------------------------

### pub fn verify(&self, pks: &PublicKeyShare<C>, sig: &SignCryptCiphertext<C>) -> BlsResult<()>

Source: https://docs.rs/blsful/4.0.0/blsful/struct.SignDecryptionShare.html

Verifies the signcryption decryption share against its corresponding public-key share and the signcryption ciphertext.

```APIDOC
## pub fn verify(&self, pks: &PublicKeyShare<C>, sig: &SignCryptCiphertext<C>) -> BlsResult<()>

### Description
Verify the signcryption decryption share against its public-key share and ciphertext.

### Parameters
- **pks** (&PublicKeyShare<C>) - The public-key share associated with the decryption share.
- **sig** (&SignCryptCiphertext<C>) - The signcryption ciphertext to verify against.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the verification is successful, or a BlsError if it fails.
```

--------------------------------

### verify_and_decrypt

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ElGamalProof.html

Verifies the proof and ciphertext, then decrypts the ciphertext using the provided secret key.

```APIDOC
## pub fn verify_and_decrypt(&self, sk: &SecretKey<C>) -> BlsResult<<C as Pairing>::PublicKey>

### Description
Verifies the proof and ciphertext, then decrypts the ciphertext.

### Parameters
- **sk** (&SecretKey<C>) - Required - The secret key used for decryption.

### Returns
- **BlsResult<<C as Pairing>::PublicKey>** - Returns the decrypted public key on success, or a BlsError if verification or decryption fails.
```

--------------------------------

### Calculate Product of Result Iterator

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Demonstrates using the product method on an iterator of Results, which short-circuits on the first Err encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### Create references with as_ref

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Converts a Result reference into a Result containing references.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### FmtForward Formatting Methods

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Provides methods to forward formatting traits to Debug output.

```rust
fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,
fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,
fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,
fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,
fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,
```

--------------------------------

### Map Result or provide default with map_or

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns a default value if Err, otherwise maps the Ok value.

```rust
let x: Result<_, &str> = Ok("foo");
assert_eq!(x.map_or(42, |v| v.len()), 3);

let x: Result<&str, _> = Err("bar");
assert_eq!(x.map_or(42, |v| v.len()), 42);
```

--------------------------------

### G2Projective Methods

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/struct.G2Projective.html

Methods for interacting with G2Projective points, including serialization, arithmetic, and group operations.

```APIDOC
## G2Projective Methods

### Serialization
- `to_compressed(&self) -> [u8; 96]`: Serializes the element into compressed form.
- `to_uncompressed(&self) -> [u8; 192]`: Serializes the element into uncompressed form.
- `from_uncompressed(bytes: &[u8; 192]) -> CtOption<G2Projective>`: Deserializes an uncompressed element.
- `from_compressed(bytes: &[u8; 96]) -> CtOption<G2Projective>`: Deserializes a compressed element.

### Arithmetic
- `double(&self) -> G2Projective`: Computes the doubling of the point.
- `add(&self, rhs: &G2Projective) -> G2Projective`: Adds the point to another G2Projective point.
- `add_mixed(&self, rhs: &G2Affine) -> G2Projective`: Adds the point to a G2Affine point.
- `sum_of_products_in_place(points: &[G2Projective], scalars: &mut [Scalar]) -> G2Projective`: Computes the sum of multiple points raised to scalars using the Pippenger method.

### Utility
- `is_identity(&self) -> Choice`: Returns true if the element is the point at infinity.
- `is_on_curve(&self) -> Choice`: Returns true if the point is on the curve.
- `batch_normalize(p: &[G2Projective], q: &mut [G2Affine])`: Converts a batch of projective elements to affine elements.
```

--------------------------------

### And Chaining

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Chains two results, returning the second if the first is Ok, otherwise returning the first Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### ProofOfPossession::verify

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ProofOfPossession.html

Verifies the proof of possession using the provided public key.

```APIDOC
## fn verify(&self, pk: &PublicKey<C>) -> BlsResult<()>

### Description
Verifies this proof of possession with a public key.

### Parameters
- **pk** (&PublicKey<C>) - Required - The public key to verify the proof against.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the verification is successful, or a BlsError if it fails.
```

--------------------------------

### ProofCommitment::generate

Source: https://docs.rs/blsful/4.0.0/blsful/enum.ProofCommitment.html

Generates a new proof-of-knowledge commitment, representing the first step in the three-step proof process.

```APIDOC
## pub fn generate<B: AsRef<[u8]>>(msg: B, signature: Signature<C>) -> BlsResult<(Self, ProofCommitmentSecret<C>)> 

### Description
Generates a new proof-of-knowledge commitment. This is step 1 in the three-step process.

### Parameters
- **msg** (B: AsRef<[u8]>) - Required - The message to be committed.
- **signature** (Signature<C>) - Required - The signature associated with the commitment.

### Returns
- **(Self, ProofCommitmentSecret<C>)** - A tuple containing the generated ProofCommitment and the associated secret.
```

--------------------------------

### MultiPublicKey::from_public_keys

Source: https://docs.rs/blsful/4.0.0/blsful/struct.MultiPublicKey.html

Accumulates a collection of public keys into a single MultiPublicKey instance.

```APIDOC
## pub fn from_public_keys<B: AsRef<[PublicKey<C>]>>(keys: B) -> BlsResult<Self>

### Description
Accumulates multiple public keys into a single public key.

### Parameters
- **keys** (B: AsRef<[PublicKey<C>]>) - Required - A collection of public keys to be accumulated.

### Returns
- **BlsResult<Self>** - Returns the accumulated MultiPublicKey or a BlsError if the operation fails.
```

--------------------------------

### Borrow and BorrowMut Implementations

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Provides standard borrowing capabilities for owned values.

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
```

--------------------------------

### Unwrap or Default Value

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the Ok value or the default value of the type if the result is an Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### ProofOfKnowledge::verify

Source: https://docs.rs/blsful/4.0.0/blsful/enum.ProofOfKnowledge.html

Verifies the proof of knowledge against a public key, message, and proof commitment challenge.

```APIDOC
## fn verify<B: AsRef<[u8]>>(&self, pk: &PublicKey<C>, msg: B, y: ProofCommitmentChallenge<C>) -> BlsResult<()>

### Description
Verifies the proof of knowledge for the given signature scheme.

### Parameters
- **pk** (&PublicKey<C>) - The public key to verify against.
- **msg** (B) - The message associated with the proof.
- **y** (ProofCommitmentChallenge<C>) - The proof commitment challenge.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the verification is successful, or an error if it fails.
```

--------------------------------

### Map Result or return default with map_or_default

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Maps the Ok value or returns the default value for the target type if Err.

```rust
let x: Result<_, &str> = Ok("foo");
let y: Result<&str, _> = Err("bar");

assert_eq!(x.map_or_default(|x| x.len()), 3);
assert_eq!(y.map_or_default(|y| y.len()), 0);
```

--------------------------------

### Bls12381G2Impl DST Implementation

Source: https://docs.rs/blsful/4.0.0/blsful/trait.BlsSignatureMessageAugmentation.html

Implementation of the domain separation tag for the Bls12381G2Impl type.

```rust
const DST: &'static [u8] = b"BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_AUG_"
```

--------------------------------

### from_shares

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ElGamalDecryptionKey.html

Combines multiple decryption shares into a single ElGamal decryption key.

```APIDOC
## pub fn from_shares(shares: &[ElGamalDecryptionShare<C>]) -> BlsResult<Self>

### Description
Combines a slice of decryption shares into an ElGamal decryption key.

### Parameters
- **shares** (&[ElGamalDecryptionShare<C>]) - A collection of decryption shares.

### Returns
- **BlsResult<Self>** - The resulting ElGamal decryption key or an error if the combination fails.
```

--------------------------------

### Bls12381G1Impl DST Implementation

Source: https://docs.rs/blsful/4.0.0/blsful/trait.BlsSignatureMessageAugmentation.html

Implementation of the domain separation tag for the Bls12381G1Impl type.

```rust
const DST: &'static [u8] = b"BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_AUG_"
```

--------------------------------

### sign_basic

Source: https://docs.rs/blsful/4.0.0/blsful/struct.SecretKeyShare.html

Signs a message using the basic signature scheme.

```APIDOC
## pub fn sign_basic(&self, msg: impl AsRef<[u8]>) -> BlsResult<SignatureShare<C>>

### Description
Signs a message using the basic BLS signature scheme.

### Parameters
- **msg** (impl AsRef<[u8]>) - The message to sign.

### Returns
- **BlsResult<SignatureShare<C>>** - The resulting signature share or an error.
```

--------------------------------

### from_shares

Source: https://docs.rs/blsful/4.0.0/blsful/struct.SignCryptDecryptionKey.html

Combines multiple decryption shares into a single signcryption decryption key.

```APIDOC
## pub fn from_shares(shares: &[SignDecryptionShare<C>]) -> BlsResult<Self>

### Description
Aggregates a collection of decryption shares to reconstruct the signcryption decryption key.

### Parameters
- **shares** (&[SignDecryptionShare<C>]) - Required - A slice of decryption shares to combine.

### Returns
- **BlsResult<Self>** - Returns the reconstructed SignCryptDecryptionKey or a BlsError if the combination fails.
```

--------------------------------

### Fallback to alternative Result with or

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the provided Result if the current one is Err. Note that arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

--------------------------------

### Define TimestampProofParts struct

Source: https://docs.rs/blsful/4.0.0/blsful/struct.TimestampProofParts.html

The structure definition for TimestampProofParts, containing the proof commitment, response, and a 64-bit timestamp.

```rust
pub struct TimestampProofParts<S> {
    pub u: S,
    pub v: S,
    pub timestamp: u64,
}
```

--------------------------------

### Pipe Utility Methods

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Provides functional piping methods for chaining operations on values.

```rust
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,
fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,
```

--------------------------------

### PublicKeyShare::verify

Source: https://docs.rs/blsful/4.0.0/blsful/struct.PublicKeyShare.html

Verifies a signature share against the public key share and a message.

```APIDOC
## fn verify<B: AsRef<[u8]>>(&self, sig: &SignatureShare<C>, msg: B) -> BlsResult<()>

### Description
Verifies the provided signature share using the current public key share and the original message.

### Parameters
- **sig** (&SignatureShare<C>) - Required - The signature share to verify.
- **msg** (B) - Required - The message that was signed, which must implement AsRef<[u8]>.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the verification succeeds, or a BlsError if it fails.
```

--------------------------------

### BlsSignaturePop Implementation for Bls12381G1Impl

Source: https://docs.rs/blsful/4.0.0/blsful/trait.BlsSignaturePop.html

Implementation of the BlsSignaturePop trait for the Bls12381G1 curve, defining specific domain separation tags.

```rust
impl BlsSignaturePop for Bls12381G1Impl
const SIG_DST: &'static [u8] = b"BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_POP_"
const POP_DST: &'static [u8] = b"BLS_POP_BLS12381G1_XMD:SHA-256_SSWU_RO_POP_"
```

--------------------------------

### And Then Chaining

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Lazily chains a function to the result if it is Ok.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}
```

--------------------------------

### PublicKey Methods

Source: https://docs.rs/blsful/4.0.0/blsful/struct.PublicKey.html

Methods available on the PublicKey struct for cryptographic operations.

```APIDOC
## sign_crypt

### Description
Encrypt a message using signcryption.

### Signature
`pub fn sign_crypt<B: AsRef<[u8]>>(&self, scheme: SignatureSchemes, msg: B) -> SignCryptCiphertext<C>`

## sign_crypt_with_rng

### Description
Encrypt a message using signcryption and a caller-provided random number generator.

### Signature
`pub fn sign_crypt_with_rng<B: AsRef<[u8]>>(&self, scheme: SignatureSchemes, msg: B, rng: impl CryptoRng) -> SignCryptCiphertext<C>`

## encrypt_time_lock

### Description
Encrypt a message using time-lock encryption.

### Signature
`pub fn encrypt_time_lock<B: AsRef<[u8]>, D: AsRef<[u8]>>(&self, scheme: SignatureSchemes, msg: B, id: D) -> BlsResult<TimeCryptCiphertext<C>>`

## encrypt_time_lock_with_rng

### Description
Encrypt a message using time-lock encryption and a caller-provided random number generator.

### Signature
`pub fn encrypt_time_lock_with_rng<B: AsRef<[u8]>, D: AsRef<[u8]>>(&self, scheme: SignatureSchemes, msg: B, id: D, rng: impl CryptoRng) -> BlsResult<TimeCryptCiphertext<C>>`

## encrypt_key_el_gamal

### Description
Encrypt a message using ElGamal.

### Signature
`pub fn encrypt_key_el_gamal(&self, sk: &SecretKey<C>) -> BlsResult<ElGamalCiphertext<C>>`

## encrypt_key_el_gamal_with_rng

### Description
Encrypt a message using ElGamal and a caller-provided random number generator.

### Signature
`pub fn encrypt_key_el_gamal_with_rng(&self, sk: &SecretKey<C>, rng: impl CryptoRng) -> BlsResult<ElGamalCiphertext<C>>`

## encrypt_key_el_gamal_with_proof

### Description
Encrypt a message using ElGamal and generate a proof.

### Signature
`pub fn encrypt_key_el_gamal_with_proof(&self, sk: &SecretKey<C>) -> BlsResult<ElGamalProof<C>>`

## encrypt_key_el_gamal_with_proof_and_rng

### Description
Encrypt a message using ElGamal, generate a proof, and use a caller-provided random number generator.

### Signature
`pub fn encrypt_key_el_gamal_with_proof_and_rng(&self, sk: &SecretKey<C>, rng: impl CryptoRng) -> BlsResult<ElGamalProof<C>>`

## from_shares

### Description
Create a public key from secret shares.

### Signature
`pub fn from_shares(shares: &[PublicKeyShare<C>]) -> BlsResult<Self>`
```

--------------------------------

### fn pairing

Source: https://docs.rs/blsful/4.0.0/blsful/trait.Pairing.html

Computes the pairing based on a slice of signature and public key point pairs.

```APIDOC
## fn pairing(points: &[(Self::Signature, Self::PublicKey)]) -> Self::PairingResult

### Description
Computes the pairing based on the supplied slice of signature and public key points.

### Parameters
- **points** (&[(Self::Signature, Self::PublicKey)]) - Required - A slice of tuples containing signature and public key points to be paired.

### Returns
- **Self::PairingResult** - The result of the pairing computation.
```

--------------------------------

### Expect Result Value

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the Ok value or panics with a provided message if the result is Err.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### scheme

Source: https://docs.rs/blsful/4.0.0/blsful/enum.TimeCryptCiphertextEnum.html

Retrieves the signature scheme used to create the ciphertext.

```APIDOC
## pub const fn scheme(&self) -> SignatureSchemes

### Description
Return the signature scheme used to create this ciphertext.

### Returns
- **SignatureSchemes** - The signature scheme identifier.
```

--------------------------------

### Unwrap Unchecked Usage

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Demonstrates the use of unwrap_unchecked to retrieve values from Ok results without safety checks.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### ProofOfKnowledge::scheme

Source: https://docs.rs/blsful/4.0.0/blsful/enum.ProofOfKnowledge.html

Returns the signature scheme associated with the proof.

```APIDOC
## fn scheme(&self) -> SignatureSchemes

### Description
Returns the signature scheme proven by this proof instance.

### Returns
- **SignatureSchemes** - The enum variant representing the signature scheme.
```

--------------------------------

### Convert Result to Option with ok

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Converts a Result into an Option, discarding the error value.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### MultiSignature::verify

Source: https://docs.rs/blsful/4.0.0/blsful/enum.MultiSignature.html

Verifies the multi-signature using the provided multi-public key and message.

```APIDOC
## pub fn verify<B: AsRef<[u8]>>(&self, pk: &MultiPublicKey<C>, msg: B) -> BlsResult<()>

### Description
Verifies the multi-signature using the multi-public key and the message that was signed.

### Parameters
- **pk** (&MultiPublicKey<C>) - Required - The multi-public key used for verification.
- **msg** (B) - Required - The message to verify against the signature.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the signature is valid, otherwise returns an error.
```

--------------------------------

### Unwrap Error

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the Err value or panics if the result is an Ok.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

--------------------------------

### Into Ok Value

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Safely extracts the Ok value from a Result that is guaranteed not to contain an error.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### pairing

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G1Impl.html

Computes the pairing result for a set of signature and public key points.

```APIDOC
## pairing(points)

### Description
Compute the pairing based on the supplied slice of signature and public key pairs.

### Parameters
- **points** (&[(Self::Signature, Self::PublicKey)]) - Required - A slice of tuples containing signature and public key points.

### Returns
- **PairingResult** (Gt) - The target group element resulting from the pairing computation.
```

--------------------------------

### Map Result values with map

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Applies a function to the Ok value of a Result.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

--------------------------------

### Retrieve value or default with unwrap_or

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the contained value or a provided default. Use unwrap_or_else for lazy evaluation.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### ElGamalProof Struct Definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ElGamalProof.html

The structure definition for ElGamalProof, parameterized by a BlsSignatureImpl implementation.

```rust
pub struct ElGamalProof<C: BlsSignatureImpl> {
    pub ciphertext: ElGamalCiphertext<C>,
    pub message_proof: <<C as Pairing>::PublicKey as Group>::Scalar,
    pub blinder_proof: <<C as Pairing>::PublicKey as Group>::Scalar,
    pub challenge: <<C as Pairing>::PublicKey as Group>::Scalar,
}
```

--------------------------------

### BlsSignature Methods

Source: https://docs.rs/blsful/4.0.0/blsful/struct.BlsSignature.html

Methods available for the BlsSignature struct to handle keys and proof challenges.

```APIDOC
## pub fn new() -> Self

### Description
Create a new BLS signature implementation.

## pub fn new_secret_key() -> SecretKey<T>

### Description
Create a new random secret key.

## pub fn secret_key_from_hash<B: AsRef<[u8]>>(data: B) -> SecretKey<T>

### Description
Compute a secret key from a hash.

## pub fn random_secret_key(rng: impl CryptoRng) -> SecretKey<T>

### Description
Compute a secret key from a CS-PRNG.

## pub fn new_proof_challenge() -> ProofCommitmentChallenge<T>

### Description
Create a new random commitment challenge for signature proofs of knowledge as step 2.

## pub fn proof_challenge_from_hash<B: AsRef<[u8]>>(data: B) -> ProofCommitmentChallenge<T>

### Description
Compute a commitment challenge for signature proofs of knowledge from a hash as step 2.

## pub fn random_proof_challenge(rng: impl CryptoRng) -> ProofCommitmentChallenge<T>

### Description
Compute a commitment challenge for signature proofs of knowledge from a CS-PRNG as step 2.
```

--------------------------------

### MultiSignature::from_signatures

Source: https://docs.rs/blsful/4.0.0/blsful/enum.MultiSignature.html

Accumulates multiple signatures into a single MultiSignature instance.

```APIDOC
## pub fn from_signatures<B: AsRef<[Signature<C>]>>(signatures: B) -> BlsResult<Self>

### Description
Accumulates a collection of signatures into a single multi-signature object.

### Parameters
- **signatures** (B) - Required - A collection of signatures to be aggregated.

### Returns
- **BlsResult<Self>** - Returns the aggregated MultiSignature or an error if accumulation fails.
```

--------------------------------

### BlsSignaturePop Implementation for Bls12381G2Impl

Source: https://docs.rs/blsful/4.0.0/blsful/trait.BlsSignaturePop.html

Implementation of the BlsSignaturePop trait for the Bls12381G2 curve, defining specific domain separation tags.

```rust
impl BlsSignaturePop for Bls12381G2Impl
const SIG_DST: &'static [u8] = b"BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_"
const POP_DST: &'static [u8] = b"BLS_POP_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_"
```

--------------------------------

### Expect Error

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Returns the Err value or panics with a custom message if the result is an Ok.

```rust
let x: Result<u32, &str> = Ok(10);
x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
```

--------------------------------

### AggregateSignature::verify

Source: https://docs.rs/blsful/4.0.0/blsful/enum.AggregateSignature.html

Verifies the aggregate signature against a set of public keys and messages.

```APIDOC
## pub fn verify<B: AsRef<[u8]>>(&self, data: &[(PublicKey<C>, B)]) -> BlsResult<()>

### Description
Verify the aggregate signature. Basic-scheme verification rejects duplicate messages as required by that ciphersuite. Message Augmentation and Proof of Possession permit them.
```

--------------------------------

### ProofCommitment::scheme

Source: https://docs.rs/blsful/4.0.0/blsful/enum.ProofCommitment.html

Returns the signature scheme associated with the current commitment.

```APIDOC
## pub const fn scheme(&self) -> SignatureSchemes 

### Description
Return the signature scheme associated with this commitment.

### Returns
- **SignatureSchemes** - The signature scheme identifier.
```

--------------------------------

### Create mutable references with as_mut

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Converts a mutable Result reference into a Result containing mutable references.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### ElGamalProofData Struct Definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ElGamalProofData.html

The structure definition for ElGamalProofData, parameterized by a group G.

```rust
pub struct ElGamalProofData<G: Group> {
    pub c1: G,
    pub c2: G,
    pub message_response: G::Scalar,
    pub blinder_response: G::Scalar,
    pub challenge: G::Scalar,
}
```

--------------------------------

### ProofOfPossession Struct Definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ProofOfPossession.html

The core structure definition for ProofOfPossession, which wraps a BLS signature.

```rust
pub struct ProofOfPossession<C: BlsSignatureImpl>(pub <C as Pairing>::Signature);
```

--------------------------------

### MultiSignature::scheme

Source: https://docs.rs/blsful/4.0.0/blsful/enum.MultiSignature.html

Returns the signature scheme used to create the multi-signature.

```APIDOC
## pub const fn scheme(&self) -> SignatureSchemes

### Description
Identifies the signature scheme (Basic, MessageAugmentation, or ProofOfPossession) associated with this instance.

### Returns
- **SignatureSchemes** - The enum variant representing the scheme.
```

--------------------------------

### Unwrap Result Value

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Extracts the Ok value or panics if the result is an Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`
```

--------------------------------

### Inspect Result

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Executes a closure with a reference to the Ok value without consuming the result.

```rust
let x: u8 = "4"
    .parse::<u8>()
    .inspect(|x| println!("original: {x}"))
    .map(|x| x.pow(3))
    .expect("failed to parse number");
```

--------------------------------

### SignatureEnum::verify

Source: https://docs.rs/blsful/4.0.0/blsful/enum.SignatureEnum.html

Verifies a BLS signature against a provided public key and message.

```APIDOC
## fn verify<B: AsRef<[u8]>>(&self, pk: &PublicKeyEnum, msg: B) -> BlsResult<()>

### Description
Verifies the signature using a public key from the same curve variant. This method ensures that the signature is valid for the given message and public key.

### Parameters
- **pk** (PublicKeyEnum) - Required - The public key to use for verification, which must correspond to the same curve variant as the signature.
- **msg** (B: AsRef<[u8]>) - Required - The message that was signed.

### Returns
- **BlsResult<()>** - Returns Ok(()) if the signature is valid, or a BlsError if verification fails.
```

--------------------------------

### Check Result with is_err_and

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Checks if the result is an Err and matches a specific predicate.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### hash_to_point

Source: https://docs.rs/blsful/4.0.0/blsful/struct.Bls12381G2Hasher.html

Computes a point in the G1Projective group from the provided message and domain separation tag.

```APIDOC
## fn hash_to_point<B: AsRef<[u8]>, C: AsRef<[u8]>>(m: B, dst: C) -> Self::Output

### Description
Computes the output point in the G1Projective group by hashing the input message using the specified domain separation tag (DST).

### Parameters
- **m** (B: AsRef<[u8]>) - The message to be hashed.
- **dst** (C: AsRef<[u8]>) - The domain separation tag used for hashing.

### Returns
- **Output** (G1Projective) - The resulting point in the G1 projective group.
```

--------------------------------

### Map Result or handle error with map_or_else

Source: https://docs.rs/blsful/4.0.0/blsful/type.BlsResult.html

Uses a fallback function for Err or a mapping function for Ok.

```rust
let k = 21;

let x : Result<_, &str> = Ok("foo");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);

let x : Result<&str, _> = Err("bar");
assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);
```

--------------------------------

### ProofOfKnowledgeTimestamp Struct Definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.ProofOfKnowledgeTimestamp.html

The core structure definition for ProofOfKnowledgeTimestamp, requiring a generic type implementing BlsSignatureImpl.

```rust
pub struct ProofOfKnowledgeTimestamp<C: BlsSignatureImpl> {
    pub proof: ProofOfKnowledge<C>,
    pub timestamp: u64,
}
```

--------------------------------

### PublicKey struct definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.PublicKey.html

The definition of the PublicKey struct, which wraps the underlying BLS public key implementation.

```rust
pub struct PublicKey<C: BlsSignatureImpl>(pub <C as Pairing>::PublicKey);
```

--------------------------------

### final_exponentiation

Source: https://docs.rs/blsful/4.0.0/blsful/inner_types/struct.MillerLoopResult.html

Performs the final exponentiation routine to convert the Miller loop result into an element of the target group Gt.

```APIDOC
### Method
`pub fn final_exponentiation(&self) -> Gt`

### Description
This method performs a final exponentiation routine to convert the result of a Miller loop into an element of `Gt`. This conversion is necessary to allow the result to be compared with other elements of the target group `Gt`.
```

--------------------------------

### Define PublicKeyShare struct

Source: https://docs.rs/blsful/4.0.0/blsful/struct.PublicKeyShare.html

The definition of the PublicKeyShare struct which wraps a pairing-based public key share.

```rust
pub struct PublicKeyShare<C: BlsSignatureImpl>(pub <C as Pairing>::PublicKeyShare);
```

--------------------------------

### SignCryptCiphertextParts Struct Definition

Source: https://docs.rs/blsful/4.0.0/blsful/struct.SignCryptCiphertextParts.html

The structure definition for SignCryptCiphertextParts, containing the ephemeral public key (u), encrypted message (v), and signature (w).

```rust
pub struct SignCryptCiphertextParts<P, S> {
    pub u: P,
    pub v: Vec<u8>,
    pub w: S,
}
```

--------------------------------

### PublicKeyEnum Definition

Source: https://docs.rs/blsful/4.0.0/blsful/enum.PublicKeyEnum.html

The structure of the PublicKeyEnum, which encapsulates either a G1 or G2 public key implementation.

```rust
pub enum PublicKeyEnum {
    G1(PublicKey<Bls12381G1Impl>),
    G2(PublicKey<Bls12381G2Impl>),
}
```

--------------------------------

### Define SECRET_KEY_BYTES constant

Source: https://docs.rs/blsful/4.0.0/blsful/constant.SECRET_KEY_BYTES.html

Represents the number of bytes required to store a secret key.

```rust
pub const SECRET_KEY_BYTES: usize = 32;
```