Skip to main content

Documentation Index

Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt

Use this file to discover all available pages before exploring further.

Try it Live

Run SIWE examples in the interactive playground

​
Constructors

Methods for creating SIWE message instances.

​
create

Create new SIWE message with automatic defaults.

​
Signature

function create<
  TDomain extends string,
  TAddress extends AddressType,
  TUri extends string,
  TChainId extends number
>(params: {
  domain: TDomain;
  address: TAddress;
  uri: TUri;
  chainId: TChainId;
  statement?: string;
  expirationTime?: string;
  notBefore?: string;
  requestId?: string;
  resources?: string[];
  nonce?: string;
  issuedAt?: string;
}): BrandedMessage<TDomain, TAddress, TUri, "1", TChainId>

​
Parameters

Required:
  • domain - RFC 4501 dns authority requesting signing
  • address - AddressType performing signing (20 bytes)
  • uri - RFC 3986 URI referring to subject of signing
  • chainId - EIP-155 Chain ID (positive integer)
Optional:
  • statement - Human-readable ASCII assertion
  • expirationTime - ISO 8601 datetime for expiration
  • notBefore - ISO 8601 datetime for not-before
  • requestId - System-specific identifier
  • resources - Array of resource URIs
  • nonce - Custom nonce (auto-generated if omitted, min 8 chars)
  • issuedAt - Custom issued time (current time if omitted)

​
Returns

BrandedMessage with:
  • version automatically set to "1"
  • nonce auto-generated if not provided (11 chars, base62)
  • issuedAt auto-set to current ISO 8601 time if not provided
  • Optional fields only included if provided

​
Example

// Minimal creation
const message = Siwe.create({
  domain: "example.com",
  address: Address("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"),
  uri: "https://example.com/login",
  chainId: 1,
});
// Auto-generates nonce and issuedAt, sets version to "1"

// Full creation with optional fields
const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com/login",
  chainId: 1,
  statement: "Sign in to access your account",
  expirationTime: "2025-12-31T23:59:59.000Z",
  notBefore: "2025-01-01T00:00:00.000Z",
  requestId: "req-abc123",
  resources: [
    "https://example.com/api/admin",
    "https://example.com/api/users",
  ],
  nonce: "customnonce12345",
  issuedAt: "2025-06-01T12:00:00.000Z",
});

// Chain-specific authentication
const mainnetAuth = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,  // Ethereum mainnet
});

const polygonAuth = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 137,  // Polygon
});

​
Type Safety

Generic parameters preserve exact types: 
const message = Siwe.create({
  domain: "example.com" as const,
  address: specificAddress,
  uri: "https://example.com" as const,
  chainId: 1 as const,
});
// message.domain: "example.com" (literal type)
// message.chainId: 1 (literal type)
// message.version: "1" (always literal "1")

​
Notes

  • Nonce generation: Uses crypto.getRandomValues() for secure randomness
  • Timestamp format: ISO 8601 format required for all timestamps
  • Version: Always “1” per EIP-4361 current specification
  • Optional fields: Only present in returned object if provided (no undefined)
  • Address format: Must be valid 20-byte AddressType

​
Common Use Cases

​
Session with Expiration

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  expirationTime: new Date(Date.now() + 3600000).toISOString(),  // 1 hour
});

​
Resource-Restricted Access

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com/admin",
  chainId: 1,
  statement: "Grant admin access",
  resources: [
    "https://example.com/api/admin/users",
    "https://example.com/api/admin/settings",
  ],
});

​
Delayed Activation

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  notBefore: new Date(Date.now() + 60000).toISOString(),  // Valid in 1 minute
  expirationTime: new Date(Date.now() + 3600000).toISOString(),  // Expires in 1 hour
});

​
Request Tracking

const requestId = crypto.randomUUID();
const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  requestId,
});
storeAuthRequest(requestId, { address: userAddress, timestamp: Date.now() });

​
Implementation Details

  • Uses conditional spreading for optional fields (no undefined values)
  • Delegates nonce generation to generateNonce()
  • Current timestamp from new Date().toISOString()
  • Version hardcoded to “1” per EIP-4361 spec
  • Returns plain object (not class instance)

​
See Also