Sign In With Solana (SIWS)

To integrate SIWS, a wallet must follow a specific lifecycle when receiving a signIn request from a dapp:

1. Receive Request: The wallet receives the signIn request.
2. Construct Message: The wallet builds a message string following the ABNF format using the provided SolanaSignInInput parameters.
3. Parse & Validate: The wallet parses the constructed message to ensure it adheres to the SIWS ABNF specification. If parsing fails, the wallet must throw an RPC error and not show the prompt to the user.
4. Verify Parameters: The wallet verifies that the parsed parameters (like domain, address, chainId, etc.) match expected values and fall within safe thresholds.
5. Prompt User:
   • If verification succeeds, show the message statement (with advanced details hidden by default).
   • If verification fails, show the prompt but include the specific verification errors.
6. Handle Response:
   • If the user accepts, the wallet signs the message and connects the user to the dapp.
   • If the user declines, the request is cancelled.
7. Return Data: Upon acceptance, the wallet returns the constructed message, the message signature, and the public address of the connected account to the dapp.

The SolanaSignInInput object should be generated on your backend server. While all fields are optional and the object can be empty in some cases, providing specific parameters improves security and context.

Key fields in SolanaSignInInput include:

• domain: The host of the dapp.
• statement: A human-readable description of the request.
• version: The SIWS version (e.g., "1").
• nonce: A unique string to prevent replay attacks.
• chainId: The network identifier (e.g., "mainnet").
• issuedAt: An ISO string representing the request time.
• resources: An array of URIs the user is interacting with.

import { SolanaSignInInput } from "@solana/wallet-standard-features";

export const createSignInData = async (): Promise<SolanaSignInInput> => {
  const now: Date = new Date();
  const uri = window.location.href;
  const currentUrl = new URL(uri);
  const domain = currentUrl.host;

  const currentDateTime = now.toISOString();

  const signInData: SolanaSignInInput = {
    domain,
    statement:
      "Clicking Sign or Approve only means you have proved this wallet is owned by you. This request will not trigger any blockchain transaction or cost any gas fee.",
    version: "1",
    nonce: "oBbLoEldZs",
    chainId: "mainnet",
    issuedAt: currentDateTime,
    resources: ["https://example.com", "https://phantom.app/"],
  };

  return signInData;
};

To automate the sign-in flow, implement an autoSignIn callback and pass it to the autoConnect prop of your WalletProvider.

Logic Flow:

1. Check if the adapter supports the signIn feature. If not, return true (to allow legacy autoConnect).
2. If supported, fetch the SolanaSignInInput from your backend.
3. Call adapter.signIn(input) to trigger the wallet request.
4. Send the input and output to your backend for verification.
5. If verification succeeds, return false (indicating the user is now signed in and the auto-connect process is handled/interrupted by the sign-in flow). If it fails, throw an error.

import { type SolanaSignInInput } from "@solana/wallet-standard-features";
import { verifySignIn } from "@solana/wallet-standard-util";

const autoSignIn = useCallback(async (adapter: Adapter) => {
  // If the signIn feature is not available, return true
  if (!("signIn" in adapter)) return true;

  // Fetch the signInInput from the backend
  const createResponse = await fetch("/backend/createSignInData");

  const input: SolanaSignInInput = await createResponse.json();

  // Send the signInInput to the wallet and trigger a sign-in request
  const output = await adapter.signIn(input);

  // Verify the sign-in output against the generated input server-side
  let strPayload = JSON.stringify({ input, output });
  const verifyResponse = await fetch("/backend/verifySIWS", {
    method: "POST",
    body: strPayload,
  });
  const success = await verifyResponse.json();

  // If verification fails, throw an error
  if (!success) throw new Error("Sign In verification failed!");

  return false;
}, []);

// Usage in component:
<WalletProvider
    wallets={wallets}
    onError={onError}
    autoConnect={autoSignIn}
>

SIWS is supported by the Solana Wallet Standard and Solana Wallet Adapter. The integration flow follows these steps:

1. Feature Detection: Check if the selected wallet has the signIn feature enabled.
2. Fallback: If signIn is not supported, use the legacy connect + signMessage mechanism.
3. Input Generation: Construct a signInInput object (containing parameters like domain, nonce, chainId, etc.) on the backend.
4. Request: Send the signInInput to the wallet via the signIn method.
5. Response: Receive the signInOutput (constructed message, signature, and public address) from the wallet.
6. Verification: Verify the returned message and signature against the original signInInput on the server-side.
7. Completion: Upon successful verification, the user is authenticated.

Messages must be constructed following the ABNF format. The @solana/wallet-standard-utils package provides a createSignInMessageText method that implements the required algorithm.

Important: While domain and address are not strictly mandatory in the SolanaSignInInput object, they are mandatory in the final constructed message. If they are missing from the input, the wallet must extract them from the requesting domain and address before construction.

export function createSignInMessageText(input: SolanaSignInInput): string {
  let message = `${input.domain} wants you to sign in with your Solana account:\n`;
  message += `${input.address}`;

  if (input.statement) {
    message += `\n\n${input.statement}`;
  }

  const fields: string[] = [];
  if (input.uri) {
    fields.push(`URI: ${input.uri}`);
  }
  if (input.version) {
    fields.push(`Version: ${input.version}`);
  }
  if (input.chainId) {
    fields.push(`Chain ID: ${input.chainId}`);
  }
  if (input.nonce) {
    fields.push(`Nonce: ${input.nonce}`);
  }
  if (input.issuedAt) {
    fields.push(`Issued At: ${input.issuedAt}`);
  }
  if (input.expirationTime) {
    fields.push(`Expiration Time: ${input.expirationTime}`);
  }
  if (input.notBefore) {
    fields.push(`Not Before: ${input.notBefore}`);
  }
  if (input.requestId) {
    fields.push(`Request ID: ${input.requestId}`);
  }
  if (input.resources) {
    fields.push(`Resources:`);
    for (const resource of input.resources) {
      fields.push(`- ${resource}`);
    }
  }
  if (fields.length) {
    message += `\n\n${fields.join("\n")}`;
  }

  return message;
}