Client Note Building
The notes you sign are built in your browser. No server builds a note for your wallet, and every note the relay hands back is checked in the browser before your wallet sees it.
Signature one: the private note to the relay
const priv = await buildClientPrivateP2id({
sender: acct, // your Miden account
target: RELAY_OPERATOR, // 0x46bbc1335b9a151147e46493504bbe
assetFaucet: QUOTE_FAUCET_ID, // USDCx on a buy; the BLUEDW vault faucet on a sell
amount: amountBase,
relayKind: "buy", // or "sell"
});It returns the serialized note (what your wallet sends) and a note file (what the relay imports). The note is a standard P2ID, NoteType.Private, tagged for the operator account. Its serial is generated in the browser and kept locally.
One measured fact shapes that API:
- A
NoteFilebuilt from an output note carries the note's details and tag but not its metadata, soNoteFile.note()andNoteFile.noteId()both come back empty. The serializedNotetravels separately.
The durable handoff
The relay needs the note file to import a private note it cannot discover by syncing. Losing that file means a stuck trade, so the handoff is a state machine in local storage (relayHandoff.ts), mounted on every page:
| State | Next step |
|---|---|
armed | Saved before the wallet prompt. Ask the chain whether the note is committed |
submitted | The wallet returned. Once committed, post the note file to the relay |
held / sent | Ask the relay for the trade's status; if it says unknown, post again with backoff |
acked | The relay holds it. Re-checked rarely |
A record is never deleted by this loop; only the final accept clears it. No wallet is involved in a resend: it is the same bytes.
The view proof
From the note's serial the browser derives the trade's proof:
const proof = await relayViewProof(noteId, serialFelts);
// sha256("darwin.relay.view.v1|" + noteId + "|" + felts.join(","))The same vectors are tested in the app (npm run test:relay-proof) and in the relay (test-proof.mjs), so the two cannot drift.
Signature two: checking the relay's note
Every note the relay returns (shares, a sell's USDCx, a buy refund) passes through guardRelayNote before any prompt:
| Check | Why |
|---|---|
Rebuild the recipient digest from the note's serial, NoteScript.p2id() and your account | Pins the script root and the target in one comparison. A foreign script or another account's note fails |
| Fungible assets only, from the expected faucets | BLUEDW for shares; USDCx or the basket's coins for a sell's return or a buy refund |
| Match what the relay declared, if it declared anything | A mismatch is refused |
On failure it throws "The relay's note was refused … nothing was signed". The wallet prompt's hint (note id, amount) is built from the parsed note, never from the relay's JSON.
Accepting in one approval
On an ordinary account the accept is a custom transaction carrying the note as an unauthenticated input note:
const request = new TransactionRequestBuilder()
.withExplicitInputNote(InputNote.unauthenticated(note))
.build();The chain authenticates it at batch time because the note is already committed. On a Guardian account the app uses requestConsume with the note's bytes instead. Success is verified against the balance, never inferred from a transaction id. See Wallets & Approvals.