Struct Sender 

pub struct Sender(/* private fields */);

A struct that a sender of funds uses in combination with a recipient’s PaymentCode in order to send notifications and calculate payment addresses. This is invariant with regard to recipient and needs to be constructed only once per account (unique per BIP32 seed + account).

Implementations

impl Sender

pub fn from_seed<C: Signing>( secp: &Secp256k1<C>, seed: &[u8], network: Network, account: u32, ) -> Result<Self, Error>

Construct a sender side from a BIP32 seed.

Examples found in repository

examples/sending.rs (line 12)

fn main() -> Result<(), bip351::Error> {
    let secp = Secp256k1::new();

    let sender = bip351::Sender::from_seed(&secp, &[0xFE], Network::Bitcoin, 0)?;

    let recipient = bip351::PaymentCode::from_str(
        "pay1qqpsxq4730l4yre4lt3588eyt3f2lwggtfalvtgfns04a8smzkn7yys6xv2gs8",
    )?;

    // Sender makes sure the recipient supports segwit addresses.
    let p2wpkh_addr_type = recipient
        .address_types()
        .get(&bip351::AddressType::P2wpkh)
        .unwrap();

    let (notification_txout, sender_recipient_commitment) =
        sender.notify(&secp, &recipient, 0, p2wpkh_addr_type.clone())?;

    // Here the sender would add `notification_txout` to a transaction and broadcast it.
    // wallet.broadcast(tx)...

    let payload = notification_txout.script_pubkey.as_bytes();
    assert_eq!(
        payload[2..].to_hex(),
        "505049cb55bb02e3217349724307eed5514b53b1f53f0802672a9913d9bbb76afecc86be23f46401"
    );

    // At this point the recipient is notified. Sender can now send funds to their secret address at index `0`.
    let recipient_addr_0 = sender.address(&secp, &sender_recipient_commitment, 0)?;
    assert_eq!(
        recipient_addr_0.to_string(),
        "bc1qw7ld5h9tj2ruwxqvetznjfq9g5jyp0gjhrs30w"
    );

    // wallet.send(&recipient_addr_0, 100000);

    Ok(())
}

examples/notify.rs (line 31)

fn main() -> std::io::Result<()> {
    let secp = bitcoin::secp256k1::Secp256k1::new();

    let payment_code = prompt("Enter the recipient's payment code").unwrap();
    let payment_code = PaymentCode::from_str(&payment_code).expect("Invalid payment code");

    let sender_seed = prompt("Enter the sender's hex-encoded BIP39 seed").unwrap();
    let sender_seed: Vec<u8> = FromHex::from_hex(&sender_seed).expect("Not a hex-encoded seed");

    let network = prompt("Enter 0 for mainnet or 1 for testnet").unwrap();
    let network = match network.as_str() {
        "0" => Network::Bitcoin,
        "1" => Network::Testnet,
        _ => panic!("unknown network"),
    };

    let recipient_index = prompt("Enter a numerical recipient index").unwrap();
    let recipient_index: u32 = recipient_index
        .parse()
        .expect("Not a valid unsigned integer");

    let sender = Sender::from_seed(&secp, &sender_seed, network, 0).unwrap();

    println!("The recipient supports the following address types:");
    let accepted_addresses: Vec<_> = payment_code.address_types().iter().collect();
    for (index, addr_type) in accepted_addresses.iter().enumerate() {
        println!("({}): {:?}", index, addr_type);
    }

    let ordinal = prompt("Pick the number next to the address type you want to use").unwrap();
    let addr_type = accepted_addresses
        .into_iter()
        .nth(ordinal.parse().expect("Not a valid integer"))
        .expect("Index out of range")
        .clone();

    let (txout, _) = sender
        .notify(&secp, &payment_code, recipient_index, addr_type)
        .unwrap();
    let payload = txout.script_pubkey.as_bytes()[2..].to_hex();
    println!("The notification OP_RETURN payload is:\n{}", payload);

    Ok(())
}

pub fn from_master_xprv<C: Signing>( secp: &Secp256k1<C>, master: ExtendedPrivKey, account: u32, ) -> Result<Self, Error>

Construct a sender side from a master extended private key. Not supplying a master key here produces an error.

pub fn notify( &self, secp: &Secp256k1<All>, payment_code: &PaymentCode, recipient_index: u32, address_type: AddressType, ) -> Result<(TxOut, SenderCommitment), Error>

Construct a notification for a payment code. The txout is an OP_RETURN consuming 0 sats. The returned SenderCommitment is used for subsequent interaction with the payment code.

recipient_index must be unique for each recipient as it uniquely defines the relationship between a sender and a recipient.

Examples found in repository

examples/sending.rs (line 25)

fn main() -> Result<(), bip351::Error> {
    let secp = Secp256k1::new();

    let sender = bip351::Sender::from_seed(&secp, &[0xFE], Network::Bitcoin, 0)?;

    let recipient = bip351::PaymentCode::from_str(
        "pay1qqpsxq4730l4yre4lt3588eyt3f2lwggtfalvtgfns04a8smzkn7yys6xv2gs8",
    )?;

    // Sender makes sure the recipient supports segwit addresses.
    let p2wpkh_addr_type = recipient
        .address_types()
        .get(&bip351::AddressType::P2wpkh)
        .unwrap();

    let (notification_txout, sender_recipient_commitment) =
        sender.notify(&secp, &recipient, 0, p2wpkh_addr_type.clone())?;

    // Here the sender would add `notification_txout` to a transaction and broadcast it.
    // wallet.broadcast(tx)...

    let payload = notification_txout.script_pubkey.as_bytes();
    assert_eq!(
        payload[2..].to_hex(),
        "505049cb55bb02e3217349724307eed5514b53b1f53f0802672a9913d9bbb76afecc86be23f46401"
    );

    // At this point the recipient is notified. Sender can now send funds to their secret address at index `0`.
    let recipient_addr_0 = sender.address(&secp, &sender_recipient_commitment, 0)?;
    assert_eq!(
        recipient_addr_0.to_string(),
        "bc1qw7ld5h9tj2ruwxqvetznjfq9g5jyp0gjhrs30w"
    );

    // wallet.send(&recipient_addr_0, 100000);

    Ok(())
}

examples/notify.rs (line 47)

fn main() -> std::io::Result<()> {
    let secp = bitcoin::secp256k1::Secp256k1::new();

    let payment_code = prompt("Enter the recipient's payment code").unwrap();
    let payment_code = PaymentCode::from_str(&payment_code).expect("Invalid payment code");

    let sender_seed = prompt("Enter the sender's hex-encoded BIP39 seed").unwrap();
    let sender_seed: Vec<u8> = FromHex::from_hex(&sender_seed).expect("Not a hex-encoded seed");

    let network = prompt("Enter 0 for mainnet or 1 for testnet").unwrap();
    let network = match network.as_str() {
        "0" => Network::Bitcoin,
        "1" => Network::Testnet,
        _ => panic!("unknown network"),
    };

    let recipient_index = prompt("Enter a numerical recipient index").unwrap();
    let recipient_index: u32 = recipient_index
        .parse()
        .expect("Not a valid unsigned integer");

    let sender = Sender::from_seed(&secp, &sender_seed, network, 0).unwrap();

    println!("The recipient supports the following address types:");
    let accepted_addresses: Vec<_> = payment_code.address_types().iter().collect();
    for (index, addr_type) in accepted_addresses.iter().enumerate() {
        println!("({}): {:?}", index, addr_type);
    }

    let ordinal = prompt("Pick the number next to the address type you want to use").unwrap();
    let addr_type = accepted_addresses
        .into_iter()
        .nth(ordinal.parse().expect("Not a valid integer"))
        .expect("Index out of range")
        .clone();

    let (txout, _) = sender
        .notify(&secp, &payment_code, recipient_index, addr_type)
        .unwrap();
    let payload = txout.script_pubkey.as_bytes()[2..].to_hex();
    println!("The notification OP_RETURN payload is:\n{}", payload);

    Ok(())
}

pub fn address( &self, secp: &Secp256k1<All>, commitment: &SenderCommitment, addr_index: u64, ) -> Result<Address, Error>

Generate an address for a recipient that has already been notified.

Examples found in repository

examples/sending.rs (line 37)

fn main() -> Result<(), bip351::Error> {
    let secp = Secp256k1::new();

    let sender = bip351::Sender::from_seed(&secp, &[0xFE], Network::Bitcoin, 0)?;

    let recipient = bip351::PaymentCode::from_str(
        "pay1qqpsxq4730l4yre4lt3588eyt3f2lwggtfalvtgfns04a8smzkn7yys6xv2gs8",
    )?;

    // Sender makes sure the recipient supports segwit addresses.
    let p2wpkh_addr_type = recipient
        .address_types()
        .get(&bip351::AddressType::P2wpkh)
        .unwrap();

    let (notification_txout, sender_recipient_commitment) =
        sender.notify(&secp, &recipient, 0, p2wpkh_addr_type.clone())?;

    // Here the sender would add `notification_txout` to a transaction and broadcast it.
    // wallet.broadcast(tx)...

    let payload = notification_txout.script_pubkey.as_bytes();
    assert_eq!(
        payload[2..].to_hex(),
        "505049cb55bb02e3217349724307eed5514b53b1f53f0802672a9913d9bbb76afecc86be23f46401"
    );

    // At this point the recipient is notified. Sender can now send funds to their secret address at index `0`.
    let recipient_addr_0 = sender.address(&secp, &sender_recipient_commitment, 0)?;
    assert_eq!(
        recipient_addr_0.to_string(),
        "bc1qw7ld5h9tj2ruwxqvetznjfq9g5jyp0gjhrs30w"
    );

    // wallet.send(&recipient_addr_0, 100000);

    Ok(())
}

pub fn network(&self) -> Network

Get the network used by this sender.

Trait Implementations

impl Clone for Sender

fn clone(&self) -> Sender

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Sender

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Sender

fn eq(&self, other: &Sender) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Sender

impl StructuralPartialEq for Sender