WebAuthForContracts

public final class WebAuthForContracts : @unchecked Sendable

Implements SEP-45 - Stellar Web Authentication for Contract Accounts.

This class provides functionality for authenticating Soroban smart contract accounts (C… addresses) through the Stellar Web Authentication protocol. The authentication flow returns a JWT token that can be used for subsequent requests to SEP-compliant services (SEP-6, SEP-12, SEP-24, SEP-31).

SEP-45 extends the SEP-10 authentication protocol to support contract accounts, which have different authentication requirements than traditional Stellar accounts. Contract accounts can implement custom authentication logic in their __check_auth function.

Typical Workflow

1. Initialize from Domain: Create a WebAuthForContracts instance using the anchor’s stellar.toml
2. Get JWT Token: Request and obtain a JWT token for authentication
3. Use Token: Include the JWT token in subsequent SEP service requests

Example Usage

// Step 1: Create WebAuthForContracts from anchor domain
let result = await WebAuthForContracts.from(
    domain: "testanchor.stellar.org",
    network: .testnet
)

switch result {
case .success(let webAuth):
    // Step 2: Get JWT token for contract account
    let contractId = "CABC..."
    let signerKeyPair = try KeyPair(secretSeed: "S...")
    let jwtResult = await webAuth.jwtToken(
        forContractAccount: contractId,
        signers: [signerKeyPair]
    )

    switch jwtResult {
    case .success(let jwtToken):
        // Step 3: Use JWT token for SEP-24, SEP-6, SEP-12, etc.
        print("JWT Token: \(jwtToken)")
    case .failure(let error):
        print("JWT token error: \(error)")
    }
case .failure(let error):
    print("WebAuth initialization error: \(error)")
}

Advanced Features

Multi-Signature Contracts:

// Provide multiple signers for contracts requiring multiple signatures
let signers = [keyPair1, keyPair2]
let result = await webAuth.jwtToken(
    forContractAccount: contractId,
    signers: signers
)

Contracts Without Signature Requirements:

// For contracts whose __check_auth doesn't require signatures
let result = await webAuth.jwtToken(
    forContractAccount: contractId,
    signers: []  // Empty signers array
)

Client Domain Signing:

// For client domain verification (mutual authentication)
let clientDomainKeyPair = try KeyPair(accountId: "G...")
let result = await webAuth.jwtToken(
    forContractAccount: contractId,
    signers: [contractSignerKeyPair],
    clientDomain: "wallet.example.com",
    clientDomainAccountKeyPair: clientDomainKeyPair,
    clientDomainSigningCallback: { entry in
        // Sign on server and return signed entry
        return try await signOnServer(entry)
    }
)

See also:

• SEP-0045 Specification
• [StellarToml] for discovering authentication endpoints
• [WebAuthenticator] for traditional account (G… and M…) authentication