Struct Holder 

pub struct Holder { /* private fields */ }

The notes one holder owns, with the one-time key of each, plus the keys it has handed out, the transfers it has signed but not yet seen land, and the payments it made until it is done with them.

It keeps the privacy rules without being told: a fresh key for every note it expects, never two notes in one transfer, transfers of one payment and refreshes spread out in time, and outputs in random order. It does no networking: submit the transfers it makes to the mint, and give it the mint’s answers.

Notes are bearer: whoever holds this store holds the money. Save it with to_json, encrypted at rest, after every change.

Implementations

impl Holder

pub fn new() -> Self

An empty store.

pub fn request( &mut self, mint: &MintView, amount: u64, ) -> Result<PaymentRequest, RequestError>

Asks for amount from mint, as the fewest notes its denominations allow, each to a fresh key.

pub fn request_at_most( &mut self, mint: &MintView, amount: u64, largest: u64, ) -> Result<PaymentRequest, RequestError>

Asks for amount from mint in notes of at most largest each. A payer whose notes are small answers PayError::Fragmented to a plain request; this request it can pay.

pub fn withdraw(&mut self, request: &PaymentRequest)

Stops expecting the notes a request asked for, for a request that will not be paid.

pub fn pay( &mut self, mint: &MintView, request: &PaymentRequest, spacing: Spacing, ) -> Result<Payment, PayError>

Answers a payment request with signed transfers.

It prefers one note that covers everything, paid in one transfer with the change back to fresh keys. Otherwise it spends several notes, one per transfer, largest first, and spaces the transfers by spacing. Only notes spendable under mint are used. The notes spent leave the store and wait among the outgoing transfers until settle or take_answers sees them answered, and the payment is kept among the payments.

Before signing anything, it refuses a request for a note the mint would not make, of an amount outside its denominations (PayError::Denomination), and a request for a note to a key it has paid already (PayError::Paid), such as the same request twice. Each planned transfer is checked against the mint’s policy as well.

pub fn absorb(&mut self, notes: &[Note]) -> u128

Takes in the notes of a mint’s answer that were made for this holder’s keys: from a payment it received, its own change, unconfirmed change included, or a refresh. Notes for other keys are ignored, and a note already held is not taken twice. Returns the value taken in.

Give it notes from the mint’s own answer, or check them first with Note::verify: the store does not check signatures.

pub fn theirs(&self, notes: &[Note]) -> Vec<Note>

The notes of a mint’s answers made for neither a note this holder holds nor a key it expects, unconfirmed change included: the counterparty’s. A payee hands them back to the payer, whose change they are, and a payer that submitted a payment hands them to the payee. They tell the counterparty nothing about this holder’s notes: they are bound to the counterparty’s own keys.

pub fn settle(&mut self, request: &TransferRequest, answer: &[Note]) -> u128

Records the mint’s answer to one of this holder’s transfers: the transfer stops being outgoing and its notes for this holder are taken in. Returns the value taken in.

When the transfer was outgoing and is part of a payment this holder made, the answer’s notes for the payee are kept for it, among the payment’s owed notes: a resend may be what carried out the payment.

pub fn take_answers(&mut self, notes: &[Note]) -> u128

Takes in notes the counterparty handed over from the mint’s answers, as absorb does, then settles each outgoing transfer that pays this holder notes, once it holds every one of them with the transfer’s mint, amount and key. Returns the value taken in.

A transfer that pays this holder nothing, such as a payment that needs no change, stays outgoing: only resending it shows it was applied.

Give it notes from the mint’s own answer, or check them first with Note::verify: the store does not check signatures, and a forged note would settle a transfer as surely as a real one.

A signature shows that the mint issued a note, not which transfer it answers. A counterparty holding the transfer can pay the same keys from notes of its own and leave the transfer unsubmitted: it then stops being outgoing though the mint never applied it, and nothing resends it before its note dies. A hand-back settles a transfer only as surely as the counterparty submitted it; to be sure, ask the mint (POST /v1/verify) whether the note the transfer spends is spent before taking the notes in.

pub fn forget(&mut self, request: &TransferRequest) -> bool

Drops an outgoing transfer whose note is gone, such as one the mint refused because its note was already spent or had expired: had the mint applied this transfer and still kept its answer, it would have answered with the notes (see resend). Returns whether the transfer was outgoing.

The mint may have applied it all the same, so the keys of its change stay, as unconfirmed change: change the counterparty hands over later is still taken in by take_answers or absorb, until the layer it would sit in is dropped (prune). The transfer leaves its payment.

pub fn cancel(&mut self, request: &TransferRequest) -> bool

Takes back the note of an outgoing transfer, for one the mint never applied, such as one nobody else holds that will never be submitted. The keys of its change stay, as unconfirmed change, and the transfer leaves its payment, as for forget. Returns whether the transfer was outgoing.

A refusal does not always show that the mint never applied it: the mint checks its policy before its record of answers, so a transfer it applied under a looser policy is refused as policy too. Once a payee holds the transfer, they can still submit it. If the mint applies it, or already had, the payee’s notes and the note taken back claim the same value, and the mint refuses whichever is spent second.

pub fn payments(&self) -> impl Iterator<Item = &MadePayment>

The payments this holder made and keeps: each while one of its transfers is outgoing, or while it keeps notes owed to the payee.

pub fn forget_owed(&mut self, notes: &[Note]) -> u128

Stops keeping notes for payees, once they are handed over: they leave the owed notes of the payments that keep them, and a payment with nothing else kept leaves the payments. Returns the value it stopped keeping.

The payee checks their signatures and takes them in, as notes from the mint’s answers: with take_answers, or absorb.

pub fn outgoing(&self) -> impl Iterator<Item = &TransferRequest>

Transfers not yet answered. Resend them after a crash or a timeout, with resend: the mint answers an identical request with the identical notes, before or after a rotation, for as long as it remembers the transfer.

pub fn at_stake(&self, request: &TransferRequest) -> Option<u128>

What this holder may lose on request if the mint applied it and its answer is lost: the value it pays to keys this holder still expects, unconfirmed change included. Some when the transfer is outgoing or pays such a key, even if the value is 0; None when nothing of this holder’s rides on it.

A transfer refused as spent or expired may have been applied after all, by the counterparty or by an earlier try whose answer was lost. A counterparty that submitted it holds the answer and can hand the notes over, for take_answers.

pub fn resend(&self, spacing: Spacing) -> Vec<ScheduledTransfer>

The outgoing transfers in random order, each with a time to resend it, spaced by spacing. Resent together, they would tell the mint their notes had one owner.

The mint answers a resent transfer with the same notes only while it keeps its answer, and at the latest until the notes it issued expire (see Error codes). After that, a transfer already applied is refused as spent or expired, and its change can only come from the counterparty, for take_answers. due_resends gives the transfers to resend before a rotation ends their chance.

pub fn due_resends(&self, mint: &MintView, now: u64) -> Vec<ScheduledTransfer>

The outgoing transfers at mint to resend before its next rotation, each at its own random moment before it, as refresh spreads its transfers from the same now. Nothing in the store changes.

A transfer is due when the note it spends dies at that rotation: after it, a transfer the mint never applied can no longer be applied. It is still due when that note was dropped at the last rotation, since the mint may keep an applied transfer’s answer until the notes it issued die, at the next. Call it before refresh, whose transfers it would list too, submit them with the refreshes and settle the answers. Resending a payment the payee has not submitted yet carries it out; the payee still gets the same notes by submitting it while the mint keeps its answer, and settling the answer keeps them for the payee too (see MadePayment::owed).

pub fn refresh(&mut self, mint: &MintView, now: u64) -> Vec<ScheduledTransfer>

Pays each of mint’s notes that dies at the next rotation to a fresh key of this holder, each at its own random moment before the rotation, so the mint cannot group one holder’s notes by when they moved. The refreshed note lands one layer later and lives as long as a received note.

Call it once per rotation period, after reading the mint’s info. Submit each transfer at its time and settle the answer.

mint alone says which notes are due: those in its first layer. now, the Unix time by the mint’s clock, says only when: the transfers are spread over the time left before the next rotation, less REFRESH_MARGIN_SECS, and are all due at once when now is at or past it, since the mint has not made it yet as far as mint knows. A clock behind the mint’s by more than that margin can spread them past the rotation, where they fail, so take now from the mint, such as from the Date of its answer.

pub fn prune(&mut self, mint: &MintView) -> u128

Removes mint’s notes whose layer was dropped and returns the value lost. It also stops waiting for unconfirmed change of mint that would sit in a dropped layer, and stops keeping notes owed to payees once their layer is dropped; neither counts as lost.

It goes by mint alone, with no clock: with a view of the mint’s info, it removes a note, and its key for good, only once the mint has dropped the note’s layer.

pub fn balance(&self, mint: &MintView) -> Balance

Value held at mint, by what it can do now.

pub fn notes(&self) -> impl Iterator<Item = &Note>

The notes held, of every mint.

pub fn to_json(&self) -> String

The whole store as JSON, secret keys included.

A store with unconfirmed change or notes owed to payees is written in format 2, which an SDK that reads only format 1 refuses rather than open without them; any other store is written in format 1.

pub fn from_json(json: &str) -> Result<Self, LoadError>

Reads a store written by to_json, by this SDK or an earlier one.

Trait Implementations

impl Clone for Holder

fn clone(&self) -> Holder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Holder

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

Formats the value using the given formatter.

impl Default for Holder

fn default() -> Holder

Returns the “default value” for a type.