Skip to content

Sign-In (SIWX)

Let users sign in by approving a CAIP-122 authentication request in D9 Wallet. Your backend verifies the cryptographic proof and establishes a session. Sign-in is off-chain and incurs no fee.

Prerequisites: walletRuntime from Quickstart and a backend capable of persisting single-use challenges.

Generate a fresh challenge for each sign-in attempt, persist it in your database, and return it to the frontend:

Field Value
domain Your exact frontend domain, e.g. dapp.example.com
uri Your exact audience URI
chains ["d9net:000000000000000000000000000000d9"]
nonce Cryptographically random, single-use string (16–128 characters)
requestId A fresh UUID
iat, exp ISO 8601 UTC timestamps to the second; use a short TTL (e.g. 5 minutes)
statement Plain-text prompt shown to the user describing what they are signing in to

Pass the backend challenge to requestWalletSignIn. It displays the pairing UI, waits for wallet approval, and returns the single CACAO proof (auth):

import { Effect, Schema } from "effect";
import { D9DAppConnector } from "@d9-network/dapp-connector";
import { D9AuthenticateParamsSchema } from "@d9-network/dapp-connector/protocol";
import { walletRuntime } from "./wallet";
export async function requestWalletSignIn(
challengePayloadFromBackend: unknown,
showPairing: (uri: string, cancel: () => Promise<void>) => void,
hidePairing: () => void,
) {
return walletRuntime.runPromise(
Effect.scoped(Effect.gen(function* () {
const connector = yield* D9DAppConnector;
const params = yield* Schema.decodeUnknownEffect(D9AuthenticateParamsSchema)(
challengePayloadFromBackend,
);
const start = yield* connector.authenticate(params);
showPairing(start.uri, () => walletRuntime.runPromise(start.cancel));
// Dismiss the pairing UI as soon as the wallet connects
yield* Effect.forkScoped(
Effect.gen(function* () {
yield* start.walletConnected;
yield* Effect.sync(hidePairing);
}),
);
const result = yield* start.response;
const [auth] = result.auths;
if (result.auths.length !== 1 || !auth) {
throw new Error("Expected exactly one approved authentication");
}
return auth;
})).pipe(Effect.ensuring(Effect.sync(hidePairing))),
);
}

3. Submit the proof to your backend (frontend)

Section titled “3. Submit the proof to your backend (frontend)”

Send auth to your backend as-is. Do not trust or pass a separate user-supplied address—your backend derives the authenticated address directly from the verified proof.

The CACAO proof contains three sections:

  • h: { t: "caip122" }
  • p: domain, iss (did:pkh:d9net:...:<address>), nonce, aud, exp, request_id, and related fields
  • s: signature algorithm (sr25519, ed25519, or ecdsa), hex signature, and public key

4. Verify the proof and issue a session (backend)

Section titled “4. Verify the proof and issue a session (backend)”

Perform all verification strictly on the server—never trust client-side assertions:

  1. Look up the stored challenge by nonce and request_id. Confirm it exists, is unexpired, and has not been consumed.
  2. Verify nbf <= now <= exp against server time.
  3. Reconstruct the canonical sign-in message from the stored challenge using serializeD9SiwxMessage from @d9-network/dapp-connector/protocol.
  4. Verify the signature over <Bytes>${siwxMessage}</Bytes>.
  5. Confirm that the public key in s corresponds to the address in p.iss; that address identifies the signed-in user.
  6. In a single atomic database transaction, mark the challenge as consumed and issue your session cookie or token to prevent replay attacks.
  • A valid sign-in proof creates a backend session.
  • Replaying the exact same proof fails at step 4.1.

If the wallet or connector returns an error, check the authentication_* codes in Troubleshooting.