Crate worgl_client 

Talks to a Worgl server over HTTP.

Two layers:

• Client makes one typed call per route of worgl-server: mint info and keys, verify, transfer, burn, mint, and the mint admin’s rotate, pause and resume, and the two routes of a playground faucet. Errors keep the mint’s stable code, such as spent or frozen, in Error::code.
• Purse puts a worgl_sdk::Holder on top: it reads mint info by itself, submits transfers at the random times the holder gives them, retries what failed on the way, and saves the holder to a Store after every change, before anything that depends on it is handed out.

The privacy rules come from the holder: a fresh key for every note, one note per transfer, and transfers of one payment, refreshes and resends spread out in time.

A payment

use worgl_client::{Client, Purse};
use worgl_sdk::Spacing;

let client = Client::new("https://mint.example.com")?;
let alice = Purse::open(client.clone(), "alice.json")?;
let bob = Purse::open(client, "bob.json")?;

// Bob asks for 5 and sends the request to Alice.
let request = bob.request(&mint, 5).await?;
// Alice answers with signed transfers and sends them to Bob.
let payment = alice.pay(&request, Spacing::default()).await?;
// Bob checks them, submits each at its time and keeps the notes.
let received = bob.receive(&request, &payment).await?;
assert_eq!(received.value, 5);
// Bob sends Alice the rest of the answers, her change, and she keeps it.
alice.accept(&received.theirs).await?;

Without the change from Bob, Alice would settle: resend her transfers, which the mint answers with the same notes while it keeps its answers. If Bob had not submitted the payment, her resend carries it out. She cannot tell, so she keeps his notes from every answer for him (see Holder::payments) until she hands them over (Purse::forget_owed) or prunes them once they expire. A transfer the mint refuses for good is dropped or cancelled (Refused::outcome).

Either side may submit a payment. When the payer does, with Purse::submit, it hands the payee’s notes from the answers, Submitted::theirs, to the payee, who takes them in with Purse::accept, and then stops keeping them with Purse::forget_owed.

Requests run on Tokio. TLS is rustls with the platform’s certificate roots.

Structs

Client

A connection to one Worgl server, which may host many mints.

FaucetInfo

What a playground faucet hands out, from GET /v1/faucet.

FileLock

A FileStore’s lock, held until it is dropped.

FileStore

A store in one file, replaced whole on every save.

Info

A mint’s info.

Locked

A store locked against other processes until this is dropped, and what was saved in it when the lock was taken.

MemoryStore

A store in memory, lost when the process ends. For tests, and for applications that persist the JSON themselves.

Purse

A Holder connected to a server and a Store: it reads mint info itself, submits transfers at their scheduled times, retries what failed on the way, and saves after every change.

Refusal

An error answer from the mint.

Refused

A transfer that did not go through, and why.

Retry

How a purse resends a transfer that failed on the way: a lost connection, a timeout, or a mint that was paused, busy or could not store it. Resending is safe, since the mint answers an identical transfer with the identical notes, before or after a rotation, for as long as it remembers the transfer (see Purse::settle).

Submitted

What submitting a set of transfers came to.

Verified

The mint’s answer about a genuine note.

Enums

Error

An error from a Client or a Purse.

Outcome

What a purse did with a transfer the mint refused.

Constants

MAX_DELAY_SECS

Longest wait honored before submitting a transfer, in seconds: a year. Later times are submitted at this delay.

Traits

Store

Where a Purse saves its Holder after every change.