Federation

public final class Federation : @unchecked Sendable

Implements SEP-0002 - Federation Protocol.

This class provides human-readable address resolution for Stellar accounts. Instead of using long cryptographic addresses (G…), users can use addresses like “alice*example.com”. Federation makes Stellar more user-friendly by mapping memorable names to account IDs.

Typical Usage

// Resolve a Stellar address to account ID
let result = await Federation.resolve(
    stellarAddress: "alice*testanchor.stellar.org"
)

switch result {
case .success(let response):
    print("Account ID: \(response.accountId)")
    if let memo = response.memo {
        print("Memo: \(memo)")
    }
case .failure(let error):
    print("Resolution failed: \(error)")
}

Reverse Lookup

// Look up address from account ID
let federation = Federation(federationAddress: "https://testanchor.stellar.org/federation")
let result = await federation.resolve(account_id: "GACCOUNT...")

if case .success(let response) = result {
    print("Stellar address: \(response.stellarAddress ?? "unknown")")
}

See also:

Show on GitHub

  • The URL of the SEP-2 federation server endpoint for resolving addresses.

    Declaration

    Swift

    public let federationAddress: String
    Show on GitHub

  • Initializes a new Federation instance with the specified federation server endpoint URL.

    Declaration

    Swift

    public init(federationAddress: String)

    Parameters

    federationAddress

    The URL of the federation server (e.g., “https://example.com/federation”)
    Show on GitHub

  • Resolves a Stellar address (e.g., “alice*example.com”) to an account ID.

    This is a convenience method that automatically discovers the federation server from the domain’s stellar.toml file and performs the resolution.

    Declaration

    Swift

    public static func resolve(stellarAddress: String, secure: Bool = true) async -> ResolveResponseEnum

    Parameters

    stellarAddress

    The Stellar address in the format “name*domain”
    secure

    If true, uses HTTPS to fetch stellar.toml (default: true)

    Return Value

    ResolveResponseEnum with the account ID and optional memo, or an error

    Show on GitHub

  • Creates a Federation instance based on information from the stellar.toml file for a given domain.

    Fetches the stellar.toml file from https://{domain}/.well-known/stellar.toml (or http:// if secure is false) and extracts the FEDERATION_SERVER URL.

    Declaration

    Swift

    public static func forDomain(domain: String, secure: Bool = true) async -> FederationForDomainEnum

    Parameters

    domain

    The domain without scheme (e.g., “example.com”)
    secure

    If true, uses HTTPS to fetch stellar.toml (default: true)

    Return Value

    FederationForDomainEnum with the Federation instance, or an error

    Show on GitHub
  • resolve(address:) Asynchronous

    Resolves a Stellar address to its federation record (type=name query).

    Performs a forward lookup from a Stellar address like “alice*example.com” to the corresponding account ID and optional memo.

    Declaration

    Swift

    public func resolve(address: String) async -> ResolveResponseEnum

    Parameters

    address

    The Stellar address in the format “name*domain”

    Return Value

    ResolveResponseEnum with account ID, memo, and other federation data, or an error

    Show on GitHub
  • resolve(account_id:) Asynchronous

    Resolves an account ID to its federation address (type=id query, reverse lookup).

    Performs a reverse lookup from a Stellar account ID (G…) to find the corresponding Stellar address like “alice*example.com”.

    Declaration

    Swift

    public func resolve(account_id: String) async -> ResolveResponseEnum

    Parameters

    account_id

    The Stellar account ID (starting with G)

    Return Value

    ResolveResponseEnum with the Stellar address, or an error

    Show on GitHub

  • Resolves a transaction ID to federation information (type=txid query).

    Used to look up the destination for a transaction that was submitted to a forwarding server.

    Declaration

    Swift

    public func resolve(transaction_id: String) async -> ResolveResponseEnum

    Parameters

    transaction_id

    The transaction hash/ID

    Return Value

    ResolveResponseEnum with federation data, or an error

    Show on GitHub

  • Resolves forwarding parameters for cross-network or cross-institution payments (type=forward query).

    Used for forwarding the payment on to a different network or different financial institution. The forwardParams of the query will vary depending on what kind of institution is the ultimate destination of the payment and what they as the forwarding anchor support.

    Declaration

    Swift

    public func resolve(forwardParams: Dictionary<String, String>) async -> ResolveResponseEnum

    Parameters

    forwardParams

    Dictionary of forwarding parameters specific to the destination institution

    Return Value

    ResolveResponseEnum with the forwarding destination, or an error

    Show on GitHub