zecfoundation
/
libbolt
mirror of https://github.com/ZcashFoundation/libbolt.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

more api updates to README

This commit is contained in:
J. Ayo Akinyele 2018-08-17 02:00:02 -04:00
parent af5ff70399
commit f0bd5546cf
2 changed files with 64 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
README.md
View File

@ -2,7 +2,7 @@
A pure-Rust library implementation of BOLT: Blind Off-chain Lightweight Transactions.
BOLT is a system for conducting privacy-preserving off-chain payments between pairs of individual parties. BOLT is designed to provide a Layer 2 payment protocol for privacy-preserving cryptocurrencies such as Zcash, by allowing individuals to establish and use payment channels for instantaneous payments that do not require an on-chain transaction.
BOLT is a system for conducting **privacy-preserving off-chain payments** between pairs of individual parties. BOLT is designed to provide a Layer 2 payment protocol for privacy-preserving cryptocurrencies such as Zcash, by allowing individuals to establish and use payment channels for instantaneous payments that do not require an on-chain transaction.
# WARNING
@ -63,11 +63,11 @@ extern crate libbolt;
# API
The libbolt library provides APIs for three types of privacy-preserving payment channels:
The libbolt library provides APIs for three types of payment channels:
* unidirectional payment channels (*work in progress*)
* bidirectional payment channels (done)
* third-party payments (done)
* bidirectional payment channels
* third-party payments
## Unidirectional Payment Channels
@ -164,12 +164,12 @@ To spend on the channel, execute the pay protocol API (can be executed as many t
### Channel Closure Algorithms
To close a channel, the customer must executes the `bidirectional::customer_refund()` routine as follows:
To close a channel, the customer must execute the `bidirectional::customer_refund()` routine as follows:
let cust_wallet = &c_data.csk;
let rc_c = bidirectional::customer_refund(&pp, &channel, &m_keypair.pk, &cust_wallet);
The merchant can dispute a customer's claim by executing the `bidirectional::merchant_retute()` routine follows:
The merchant can dispute a customer's claim by executing the `bidirectional::merchant_retute()` routine as follows:
let channel_token = &c_data.channel_token;
let rc_m = bidirectional::merchant_refute(&pp, &mut channel, &channel_token, &m_data, &rc_c, &rv_w.signature);
@ -184,7 +184,46 @@ To resolve a dispute between a customer and a merchant, the following routine is
## Third-party Payment Support
**TODO**
The bidirectional payment channels can be used to construct third-party payments in which a party **A** pays a second party **B** through an untrusted intermediary (**I**) to which both **A** and **B** have already established a channel. With BOLT, the intermediary learns nothing about the payment from **A** to **B** and cannot link transactions to individual users.
To enable third-party payment support, initialize each payment channel as follows:
let pp = bidirectional::setup(true);
// create the channel state for each channel and indicate third-party support
let mut channel_a = bidirectional::ChannelState::new(String::from("Channel A -> I"), true);
let mut channel_b = bidirectional::ChannelState::new(String::from("Channel B -> I"), true);
Moreover, the intermediary can set a channel fee as follows:
channel_a.set_channel_fee(5);
The channel establishment still works as described before and the pay protocol includes an additional step to verify that the payments on both channels cancel out or include a channel fee (if specified).
...
let payment_amount = 20;
// get payment proof on first channel with party A (and I)
let (t_c1, new_w1, pay_proof1) = bidirectional::pay_by_customer_phase1(&pp, &channel_a,
&c1_data.channel_token, // channel token
&merch_keys.pk, // merchant pub key
&c1_data.csk, // wallet
payment_amount); // bal inc
// get payment proof on second channel with party B (and I)
let (t_c2, new_w2, pay_proof2) = bidirectional::pay_by_customer_phase1(&pp, &channel2,
&c2_data.channel_token, // channel token
&m_keys.pk, // merchant pub key
&c2_data.csk, // wallet
-payment_amount); // bal dec
// verify that the payment proof is valid and cancels out or results in a fee
let tx_fee = channel_a.get_channel_fee() + channel_b.get_channel_fee();
assert!(bidirectional::verify_third_party_payment(&pp, tx_fee, &pay_proof1.bal_proof, &pay_proof2.bal_proof));
...
# Documentation

36
src/lib.rs
View File

@ -1028,9 +1028,9 @@ pub mod bidirectional {
// add specified wpk to make the proof valid
// NOTE: if valid, then wpk is indeed the wallet public key for the wallet
let new_C = proof_old_cv.C + bal_proof.old_bal_com + (proof.old_com_base * hash_pub_key_to_fr(&proof.wpk));
let new_c = proof_old_cv.C + bal_proof.old_bal_com + (proof.old_com_base * hash_pub_key_to_fr(&proof.wpk));
let new_proof_old_cv = clproto::ProofCV { T: proof_old_cv.T,
C: new_C,
C: new_c,
s: proof_old_cv.s.clone(),
pub_bases: proof_old_cv.pub_bases.clone(),
num_secrets: proof_old_cv.num_secrets };
@ -1644,41 +1644,41 @@ mod tests {
let pp = bidirectional::setup(true);
// third party -- so indicate so in the channel state
let mut channelA = bidirectional::ChannelState::new(String::from("Channel A -> I"), true);
let mut channelB = bidirectional::ChannelState::new(String::from("Channel B -> I"), true);
let mut channel_a = bidirectional::ChannelState::new(String::from("Channel A -> I"), true);
let mut channel_b = bidirectional::ChannelState::new(String::from("Channel B -> I"), true);
let fee = 2;
channelA.set_channel_fee(fee);
channel_a.set_channel_fee(fee);
let total_payment = 20;
let b0_alice = 30;
let b0_bob = 30;
let b0_merchantA = 40;
let b0_merchantB = 40;
let b0_merchant_a = 40;
let b0_merchant_b = 40;
let (merch_keys, mut merch_data_A, alice_keys, mut alice_data) = setup_new_channel_helper(&pp, &mut channelA, b0_alice, b0_merchantA);
let (merch_keys, mut merch_data_a, alice_keys, mut alice_data) = setup_new_channel_helper(&pp, &mut channel_a, b0_alice, b0_merchant_a);
let (mut merch_data_B, bob_keys, mut bob_data) =
setup_new_channel_existing_merchant_helper(&pp, &mut channelB, b0_bob, b0_merchantB, &merch_keys);
let (mut merch_data_b, bob_keys, mut bob_data) =
setup_new_channel_existing_merchant_helper(&pp, &mut channel_b, b0_bob, b0_merchant_b, &merch_keys);
// run establish protocol for alice and merchant channel
execute_establish_protocol_helper(&pp, &mut channelA, &merch_keys, &mut merch_data_A, &alice_keys, &mut alice_data);
execute_establish_protocol_helper(&pp, &mut channel_a, &merch_keys, &mut merch_data_a, &alice_keys, &mut alice_data);
// run establish protocol for bob and merchant channel
execute_establish_protocol_helper(&pp, &mut channelB, &merch_keys, &mut merch_data_B, &bob_keys, &mut bob_data);
execute_establish_protocol_helper(&pp, &mut channel_b, &merch_keys, &mut merch_data_b, &bob_keys, &mut bob_data);
assert!(channelA.channel_established);
assert!(channelB.channel_established);
assert!(channel_a.channel_established);
assert!(channel_b.channel_established);
// alice can pay bob through the merchant
execute_third_party_pay_protocol_helper(&pp, &mut channelA, &mut channelB,
&merch_keys, &mut merch_data_A, &mut merch_data_B,
execute_third_party_pay_protocol_helper(&pp, &mut channel_a, &mut channel_b,
&merch_keys, &mut merch_data_a, &mut merch_data_b,
&alice_keys, &mut alice_data, &bob_keys, &mut bob_data, total_payment);
println!("Customer alice balance: {}", alice_data.csk.balance);
println!("Merchant channel balance with alice: {}", merch_data_A.csk.balance);
println!("Merchant channel balance with alice: {}", merch_data_a.csk.balance);
println!("Customer bob balance: {}", bob_data.csk.balance);
println!("Merchant channel balance with bob: {}", merch_data_B.csk.balance);
println!("Merchant channel balance with bob: {}", merch_data_b.csk.balance);
}
}