Skip to main content
@tevm/voltaire
@tevm/voltaire / primitives/Siwe

​
primitives/Siwe

​
Classes

​
InvalidFieldError

Defined in: src/primitives/Siwe/errors.js:59 SIWE message field has invalid value

​
Throws

​
Extends

​
Constructors

Constructor
new InvalidFieldError(field, reason, options?): InvalidFieldError
Defined in: src/primitives/Siwe/errors.js:67
Parameters
field
string Name of the invalid field
reason
string Why the field is invalid
options?
cause?
Error
value?
unknown
Returns
InvalidFieldError
Overrides
InvalidFormatError.constructor

​
Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
InvalidFormatError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
InvalidFormatError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
InvalidFormatError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
InvalidFormatError.docsPath
expected
expected: string
Defined in: src/primitives/errors/ValidationError.ts:19
Inherited from
InvalidFormatError.expected
name
name: string
Defined in: src/primitives/Siwe/errors.js:75
Inherited from
InvalidFormatError.name
value
value: unknown
Defined in: src/primitives/errors/ValidationError.ts:18
Inherited from
InvalidFormatError.value

​
Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
InvalidFormatError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
InvalidFormatError.toJSON

​
InvalidNonceLengthError

Defined in: src/primitives/Siwe/errors.js:84 SIWE nonce length is invalid

​
Throws

​
Extends

​
Constructors

Constructor
new InvalidNonceLengthError(length, options?): InvalidNonceLengthError
Defined in: src/primitives/Siwe/errors.js:90
Parameters
length
number Requested nonce length
options?
cause?
Error
Returns
InvalidNonceLengthError
Overrides
InvalidLengthError.constructor

​
Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
InvalidLengthError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
InvalidLengthError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
InvalidLengthError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
InvalidLengthError.docsPath
expected
expected: string
Defined in: src/primitives/errors/ValidationError.ts:19
Inherited from
InvalidLengthError.expected
name
name: string
Defined in: src/primitives/Siwe/errors.js:98
Inherited from
InvalidLengthError.name
value
value: unknown
Defined in: src/primitives/errors/ValidationError.ts:18
Inherited from
InvalidLengthError.value

​
Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
InvalidLengthError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
InvalidLengthError.toJSON

​
InvalidSiweMessageError

Defined in: src/primitives/Siwe/errors.js:12 SIWE message format is invalid

​
Throws

​
Extends

​
Constructors

Constructor
new InvalidSiweMessageError(message, options?): InvalidSiweMessageError
Defined in: src/primitives/Siwe/errors.js:19
Parameters
message
string Description of the format issue
options?
cause?
Error
value?
unknown
Returns
InvalidSiweMessageError
Overrides
InvalidFormatError.constructor

​
Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
InvalidFormatError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
InvalidFormatError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
InvalidFormatError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
InvalidFormatError.docsPath
expected
expected: string
Defined in: src/primitives/errors/ValidationError.ts:19
Inherited from
InvalidFormatError.expected
name
name: string
Defined in: src/primitives/Siwe/errors.js:27
Inherited from
InvalidFormatError.name
value
value: unknown
Defined in: src/primitives/errors/ValidationError.ts:18
Inherited from
InvalidFormatError.value

​
Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
InvalidFormatError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
InvalidFormatError.toJSON

​
MissingFieldError

Defined in: src/primitives/Siwe/errors.js:36 SIWE message missing required field

​
Throws

​
Extends

​
Constructors

Constructor
new MissingFieldError(field, options?): MissingFieldError
Defined in: src/primitives/Siwe/errors.js:42
Parameters
field
string Name of the missing field
options?
cause?
Error
Returns
MissingFieldError
Overrides
InvalidFormatError.constructor

​
Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
InvalidFormatError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
InvalidFormatError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
InvalidFormatError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
InvalidFormatError.docsPath
expected
expected: string
Defined in: src/primitives/errors/ValidationError.ts:19
Inherited from
InvalidFormatError.expected
name
name: string
Defined in: src/primitives/Siwe/errors.js:50
Inherited from
InvalidFormatError.name
value
value: unknown
Defined in: src/primitives/errors/ValidationError.ts:18
Inherited from
InvalidFormatError.value

​
Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
InvalidFormatError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
InvalidFormatError.toJSON

​
SiweParseError

Defined in: src/primitives/Siwe/errors.js:107 SIWE message parsing failed

​
Throws

​
Extends

​
Constructors

Constructor
new SiweParseError(message, options?): SiweParseError
Defined in: src/primitives/Siwe/errors.js:114
Parameters
message
string Description of the parse error
options?
cause?
Error
value?
unknown
Returns
SiweParseError
Overrides
DecodingError.constructor

​
Properties

cause?
optional cause: Error
Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)
Inherited from
DecodingError.cause
code
code: string
Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling
Example
'INVALID_FORMAT', 'INVALID_LENGTH'
Inherited from
DecodingError.code
context?
optional context: Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging
Example
{ value: '0x123', expected: '20 bytes' }
Inherited from
DecodingError.context
docsPath?
optional docsPath: string
Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error
Example
'/primitives/address/from-hex#error-handling'
Inherited from
DecodingError.docsPath
name
name: string
Defined in: src/primitives/Siwe/errors.js:121
Inherited from
DecodingError.name

​
Methods

getErrorChain()
getErrorChain(): string
Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging
Returns
string
Inherited from
DecodingError.getErrorChain
toJSON()
toJSON(): Record<string, unknown>
Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry
Returns
Record<string, unknown>
Inherited from
DecodingError.toJSON

​
Type Aliases

​
BrandedMessage

BrandedMessage<TDomain, TAddress, TUri, TVersion, TChainId> = SiweMessageType<TDomain, TAddress, TUri, TVersion, TChainId>
Defined in: src/primitives/Siwe/SiweMessageType.ts:74 Branded SIWE Message type (for backwards compatibility)

​
Type Parameters

TDomain
TDomain extends string = string
TAddress
TAddress extends AddressType = AddressType
TUri
TUri extends string = string
TVersion
TVersion extends string = string
TChainId
TChainId extends number = number

​
Deprecated

Use SiweMessageType instead

​
Signature

Signature = Uint8Array
Defined in: src/primitives/Siwe/SiweMessageType.ts:46 Signature type for SIWE verification 65 bytes: r (32) + s (32) + v (1)

​
SiweMessageType

SiweMessageType<TDomain, TAddress, TUri, TVersion, TChainId> = object
Defined in: src/primitives/Siwe/SiweMessageType.ts:9 Sign-In with Ethereum Message (EIP-4361) A structured message format for authentication using Ethereum accounts. Supports domains, URIs, nonces, timestamps, and optional resources.

​
Type Parameters

TDomain
TDomain extends string = string
TAddress
TAddress extends AddressType = AddressType
TUri
TUri extends string = string
TVersion
TVersion extends string = string
TChainId
TChainId extends number = number

​
Properties

address
address: TAddress
Defined in: src/primitives/Siwe/SiweMessageType.ts:19 Ethereum address performing the signing
chainId
chainId: TChainId
Defined in: src/primitives/Siwe/SiweMessageType.ts:27 EIP-155 Chain ID to which the session is bound
domain
domain: TDomain
Defined in: src/primitives/Siwe/SiweMessageType.ts:17 RFC 4501 dns authority that is requesting the signing
expirationTime?
optional expirationTime: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:33 ISO 8601 datetime string after which the message is no longer valid (optional)
issuedAt
issuedAt: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:31 ISO 8601 datetime string of the current time
nonce
nonce: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:29 Randomized token to prevent replay attacks, at least 8 alphanumeric characters
notBefore?
optional notBefore: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:35 ISO 8601 datetime string before which the message is invalid (optional)
requestId?
optional requestId: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:37 System-specific identifier that may be used to uniquely refer to the sign-in request (optional)
resources?
optional resources: string[]
Defined in: src/primitives/Siwe/SiweMessageType.ts:39 List of information or references to information the user wishes to have resolved (optional)
statement?
optional statement: string
Defined in: src/primitives/Siwe/SiweMessageType.ts:21 Human-readable ASCII assertion that the user will sign (optional)
uri
uri: TUri
Defined in: src/primitives/Siwe/SiweMessageType.ts:23 RFC 3986 URI referring to the resource that is the subject of the signing
version
version: TVersion
Defined in: src/primitives/Siwe/SiweMessageType.ts:25 Current version of the message (must be “1”)

​
ValidationError

ValidationError = { message: string; type: "invalid_domain"; } | { message: string; type: "invalid_address"; } | { message: string; type: "invalid_uri"; } | { message: string; type: "invalid_version"; } | { message: string; type: "invalid_chain_id"; } | { message: string; type: "invalid_nonce"; } | { message: string; type: "invalid_timestamp"; } | { message: string; type: "expired"; } | { message: string; type: "not_yet_valid"; } | { message: string; type: "signature_mismatch"; }
Defined in: src/primitives/Siwe/SiweMessageType.ts:58 Validation error types

​
ValidationResult

ValidationResult = { valid: true; } | { error: ValidationError; valid: false; }
Defined in: src/primitives/Siwe/SiweMessageType.ts:51 Validation result with detailed error information

​
Variables

​
_getMessageHash

const _getMessageHash: GetMessageHashFn
Defined in: src/primitives/Siwe/index.ts:78

​
_verify

const _verify: VerifyFn
Defined in: src/primitives/Siwe/index.ts:79

​
_verifyMessage

const _verifyMessage: VerifyMessageFn
Defined in: src/primitives/Siwe/index.ts:84

​
BrandedSiwe

const BrandedSiwe: object
Defined in: src/primitives/Siwe/index.ts:156

​
Type Declaration

create()
create: <TDomain, TAddress, TUri, TChainId>(params) => SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>
Type Parameters
TDomain
TDomain extends string = string
TAddress
TAddress extends AddressType = AddressType
TUri
TUri extends string = string
TChainId
TChainId extends number = number
Parameters
params
CreateParams<TDomain, TAddress, TUri, TChainId>
Returns
SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>
format()
format: (message) => string
Parameters
message
SiweMessageType
Returns
string
generateNonce()
generateNonce: (length?) => string
Parameters
length?
number
Returns
string
getMessageHash
getMessageHash: GetMessageHashFn
parse()
parse: (text) => SiweMessageType
Parameters
text
string
Returns
SiweMessageType
validate()
validate: (message, options?) => ValidationResult
Parameters
message
SiweMessageType
options?
now?
Date
Returns
ValidationResult
verify
verify: VerifyFn
verifyMessage
verifyMessage: VerifyMessageFn

​
GetMessageHash()

const GetMessageHash: (deps) => GetMessageHashFn
Defined in: src/primitives/Siwe/index.ts:46

​
Parameters

deps
keccak256
(data) => Uint8Array

​
Returns

GetMessageHashFn

​
Verify()

const Verify: (deps) => VerifyFn
Defined in: src/primitives/Siwe/index.ts:50

​
Parameters

deps
addressFromPublicKey
(x, y) => AddressType
keccak256
(data) => Uint8Array
secp256k1RecoverPublicKey
(signature, hash) => Secp256k1PublicKeyType

​
Returns

VerifyFn

​
VerifyMessage()

const VerifyMessage: (deps) => VerifyMessageFn
Defined in: src/primitives/Siwe/index.ts:59

​
Parameters

deps
addressFromPublicKey
(x, y) => AddressType
keccak256
(data) => Uint8Array
secp256k1RecoverPublicKey
(signature, hash) => Secp256k1PublicKeyType

​
Returns

VerifyMessageFn

​
Functions

​
_create()

_create<TDomain, TAddress, TUri, TChainId>(params): SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>
Defined in: src/primitives/Siwe/create.js:40 Create a new SIWE message with default values

​
Type Parameters

TDomain
TDomain extends string
TAddress
TAddress extends AddressType
TUri
TUri extends string
TChainId
TChainId extends number

​
Parameters

params
Message parameters (domain, address, uri, chainId are required)
address
TAddress Ethereum address performing the signing
chainId
TChainId EIP-155 Chain ID
domain
TDomain RFC 4501 dns authority requesting the signing
expirationTime?
string ISO 8601 datetime string for expiration
issuedAt?
string Custom issued at (current time if not provided)
nonce?
string Custom nonce (auto-generated if not provided)
notBefore?
string ISO 8601 datetime string for not before
requestId?
string System-specific identifier
resources?
string[] List of resources
statement?
string Human-readable ASCII assertion
uri
TUri RFC 3986 URI referring to the subject of signing

​
Returns

SiweMessageType<TDomain, TAddress, TUri, "1", TChainId> New SIWE message with defaults

​
See

https://voltaire.tevm.sh/primitives/siwe for SIWE documentation

​
Since

0.0.0

​
Throws

​
Example

import * as Siwe from './primitives/Siwe/index.js';
import * as Address from './primitives/Address/index.js';
const message = Siwe.create({
  domain: "example.com",
  address: Address.fromHex("0x..."),
  uri: "https://example.com",
  chainId: 1,
});
// Automatically generates nonce, issuedAt, and sets version to "1"

​
_format()

_format(message): string
Defined in: src/primitives/Siwe/format.js:26 Format a SIWE message into a string for signing (EIP-4361)

​
Parameters

message
SiweMessageType<string, AddressType, string, string, number> Message to format

​
Returns

string Formatted string according to EIP-4361 specification

​
See

https://voltaire.tevm.sh/primitives/siwe for SIWE documentation

​
Since

0.0.0

​
Throws

​
Example

import * as Siwe from './primitives/Siwe/index.js';
import * as Address from './primitives/Address/index.js';
const message = {
  domain: "example.com",
  address: Address.fromHex("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"),
  uri: "https://example.com",
  version: "1",
  chainId: 1,
  nonce: "32891756",
  issuedAt: "2021-09-30T16:25:24Z",
};

const text = Siwe.format(message);

​
_generateNonce()

_generateNonce(length?): string
Defined in: src/primitives/Siwe/generateNonce.js:22 Generate a cryptographically secure random nonce for SIWE messages

​
Parameters

length?
number = 11 Length of nonce (minimum 8)

​
Returns

string Random alphanumeric nonce string

​
See

https://voltaire.tevm.sh/primitives/siwe for SIWE documentation

​
Since

0.0.0

​
Throws

if length is less than 8

​
Example

import * as Siwe from './primitives/Siwe/index.js';
const nonce = Siwe.generateNonce();
// Returns something like "a7b9c2d4e6f"

const longNonce = Siwe.generateNonce(16);
// Returns something like "a7b9c2d4e6f8g0h1"

​
_parse()

_parse(text): SiweMessageType<string, AddressType, string, string, number>
Defined in: src/primitives/Siwe/parse.js:39 Parse a SIWE message from a formatted string

​
Parameters

text
string Formatted SIWE message string

​
Returns

SiweMessageType<string, AddressType, string, string, number> Parsed Message object

​
See

https://voltaire.tevm.sh/primitives/siwe for SIWE documentation

​
Since

0.0.0

​
Throws

if message format is invalid

​
Throws

if required field is missing

​
Throws

if field value is invalid

​
Throws

if parsing fails

​
Example

import * as Siwe from './primitives/Siwe/index.js';
const text = `example.com wants you to sign in with your Ethereum account:
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Sign in to Example

URI: https://example.com
Version: 1
Chain ID: 1
Nonce: 32891756
Issued At: 2021-09-30T16:25:24Z`;

const message = Siwe.parse(text);

​
_validate()

_validate(message, options?): ValidationResult
Defined in: src/primitives/Siwe/validate.js:20 Validate a SIWE message structure and timestamps

​
Parameters

message
SiweMessageType<string, AddressType, string, string, number> Message to validate
options?
Validation options
now?
Date Current time for timestamp checks (defaults to now)

​
Returns

ValidationResult Validation result with error details if invalid

​
See

https://voltaire.tevm.sh/primitives/siwe for SIWE documentation

​
Since

0.0.0

​
Throws

​
Example

import * as Siwe from './primitives/Siwe/index.js';
const result = Siwe.validate(message);
if (!result.valid) {
  console.error(result.error.message);
}

​
create()

create<TDomain, TAddress, TUri, TChainId>(params): SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>
Defined in: src/primitives/Siwe/index.ts:110

​
Type Parameters

TDomain
TDomain extends string = string
TAddress
TAddress extends AddressType = AddressType
TUri
TUri extends string = string
TChainId
TChainId extends number = number

​
Parameters

params
CreateParams<TDomain, TAddress, TUri, TChainId>

​
Returns

SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>

​
format()

format(message): string
Defined in: src/primitives/Siwe/index.ts:121

​
Parameters

message
SiweMessageType

​
Returns

string

​
generateNonce()

generateNonce(length?): string
Defined in: src/primitives/Siwe/index.ts:125

​
Parameters

length?
number

​
Returns

string

​
parse()

parse(text): SiweMessageType
Defined in: src/primitives/Siwe/index.ts:129

​
Parameters

text
string

​
Returns

SiweMessageType

​
Siwe()

Siwe<TDomain, TAddress, TUri, TChainId>(params): SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>
Defined in: src/primitives/Siwe/index.ts:170 Factory function for creating SIWE Message instances

​
Type Parameters

TDomain
TDomain extends string = string
TAddress
TAddress extends AddressType = AddressType
TUri
TUri extends string = string
TChainId
TChainId extends number = number

​
Parameters

params
CreateParams<TDomain, TAddress, TUri, TChainId>

​
Returns

SiweMessageType<TDomain, TAddress, TUri, "1", TChainId>

​
validate()

validate(message, options?): ValidationResult
Defined in: src/primitives/Siwe/index.ts:133

​
Parameters

message
SiweMessageType
options?
now?
Date

​
Returns

ValidationResult

​
References

​
getMessageHash

Renames and re-exports _getMessageHash

​
verify

Renames and re-exports _verify

​
verifyMessage

Renames and re-exports _verifyMessage