Design Dusk-native typed intent signing for dApps

[HDauven]

Summary

dusk_signMessage is a low-level opaque byte-signing primitive. Even with domain separation, it is not the right long-term UX/security model for dApp authorization, contract actions, data-driver workflows, or other human-meaningful intents.

This issue tracks the larger product/protocol design for Dusk-native typed intent signing.

The short-term dusk_signMessage approval UI hardening is tracked separately in #24.

Goals

Introduce a typed signing model that lets the wallet render what the user is authorizing, while giving dApps and verifiers a canonical envelope they can validate.

The design should bind at least:

• origin
• chain ID
• account/public key
• intent type
• nonce
• issued-at timestamp
• expiry
• human-readable statement or summary
• canonical payload hash
• optional schema/data-driver/contract context

Possible provider method

dusk_signIntent({
  type,
  nonce,
  expiresAt,
  statement,
  payload,
  payloadSchema?,
  contractId?,
  fnName?,
  dataDriverVersion?,
})

Possible signed envelope

Dusk Connect SignIntent v1
Origin: https://example.app
Chain ID: dusk:1
Account: <BLS public account>
Intent Type: login | contract-action | driver-upload | generic
Issued At: <ISO timestamp>
Expiration Time: <ISO timestamp>
Nonce: <dApp nonce>
Payload Schema: <schema id or data-driver id>
Payload Hash: 0x...
Payload:
<canonical JSON or typed summary>

Design questions

• Should this use a direct BLS signing export from the browser wallet/core path instead of the current dummy Moonlight memo transaction technique?
• What canonical serialization should be used for typed payloads?
• Which intent types should be supported in v1?
• How should connect expose verifier helpers?
• How should data drivers participate in rendering and validating contract-call payloads?
• What should be rejected by policy instead of merely displayed?

Expected output

• A concrete intent envelope specification.
• Wallet UI rendering rules for each supported intent type.
• Verification helpers or API shape for connect.
• Migration guidance for dApps currently using dusk_signMessage for login/auth flows.
• Tests covering origin/chain/account binding, nonce/expiry handling, and canonical payload hashing.

Related issue

• Improve dusk_signMessage approval UI for readable and opaque messages #24 handles the immediate dusk_signMessage approval UI improvement.

[ichbindas]

Related short-term ask: raw BLS digest signing

Opened #90 for a Connect RPC that signs an exact 32-byte digest with the profile Moonlight BLS key (sk.sign(digest) under DST BLS_SIG_BLS12381G1_XMD:SHA-256_DUSK_V2), returns { fundsPkHex, signatureHex }, and does not submit a transaction.

That is aimed at contract flows where on-chain code already computed digest = H(domain ‖ fields…) and verifies pk.verify(sig, digest). Stock dusk_signMessage / dusk_signAuth wrap caller input in a memo envelope and sign via the Moonlight memo path, so the signature does not verify against that digest.

How this relates to typed intent (#22)

#90 is a narrow bridge, not a substitute for typed intent:

	#90 raw digest	#22 typed intent
Goal	Contract-verifiable BLS over a precomputed digest	Human-meaningful authorization UX + canonical envelope
Wallet renders	Digest hex (+ optional short label later)	Intent type, statement, bound origin/chain/account, …
Who builds the digest / payload	dApp / contract ABI layer	Spec + wallet (+ optional schema/data-driver)

One of the design questions here asks whether intent signing should use a direct BLS export instead of the dummy Moonlight memo technique. #90 is evidence that some dApps already need that direct path for digest-verified contract calls; typed intent can still layer a richer envelope on top (or beside) it later.

[ichbindas]

dusk_signTypedData (wallet#101, with dusk-network/connect#35) is a generic typed-data primitive rather than the dusk_signIntent envelope sketched here. The reasoning, since the PR body states the design without arguing it against this issue:

Every binding listed here is expressible as a typed schema. The wallet enforces the two a dApp must not control — origin, injected by the wallet and bound into the digest, and chainId, which must match the active chain or the request is rejected before any approval UI appears. Intent type, nonce, issued-at, expiry, statement, and payload context live in the schema and are covered by the digest.

The wallet binds those fields; it does not police them. It cannot check a nonce against a dApp's server state, and expiry is the verifier's decision, not the signer's. Binding them into the signed digest is what makes them tamper-evident, and that part is covered.

Why generic rather than a fixed envelope: a fixed envelope costs a wallet release for every new intent type. That is what makes "which intent types should be supported in v1?" a hard question to answer. Typed data removes it — third parties ship new schemas with no store release, and a SignIn envelope becomes an SDK preset rather than a wallet feature. Presets stay convenience, never a wallet gate.

Design questions this settles:

• Direct BLS export vs the dummy Moonlight memo technique — direct BLS. The memo path cannot produce a signature a contract can verify against its own digest.
• Canonical serialization — specified in Connect (docs/typed-data-v1.md), with golden vectors carrying per-stage intermediates so two implementations can be compared on where they diverge, not merely that they do.
• How Connect exposes verifier helpers — @dusk/connect/bls.
• What policy rejects rather than displays — chain mismatch, malformed types, missing primary type, and oversized payloads, all rejected before the approval window opens.

Deliberately left open:

• Data drivers participating in rendering and validating contract-call payloads.
• Migration guidance for dApps currently using dusk_signMessage for login.

Both are easier to decide once the primitive is in, and neither blocks it.

---