Documentation
client-notes

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 NoteFile built from an output note carries the note's details and tag but not its metadata, so NoteFile.note() and NoteFile.noteId() both come back empty. The serialized Note travels 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:

StateNext step
armedSaved before the wallet prompt. Ask the chain whether the note is committed
submittedThe wallet returned. Once committed, post the note file to the relay
held / sentAsk the relay for the trade's status; if it says unknown, post again with backoff
ackedThe 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:

CheckWhy
Rebuild the recipient digest from the note's serial, NoteScript.p2id() and your accountPins the script root and the target in one comparison. A foreign script or another account's note fails
Fungible assets only, from the expected faucetsBLUEDW 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 anythingA 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.