SEPs / Federation

Federation.FEDERATION_RESPONSE_MAX_SIZE

The maximum size of response from a federation server

const FEDERATION_RESPONSE_MAX_SIZE: number

Source: src/federation/server.ts:15

Federation.Server

Federation.Server handles a network connection to a federation server instance and exposes an interface for requests to that instance.

class Server {
  constructor(serverURL: string, domain: string, opts: Options = {});
  static createForDomain(domain: string, opts: Options = {}): Promise<FederationServer>;
  static resolve(value: string, opts: Options = {}): Promise<Record>;
  resolveAccountId(accountId: string): Promise<Record>;
  resolveAddress(address: string): Promise<Record>;
  resolveTransactionId(transactionId: string): Promise<Record>;
}

Source: src/federation/server.ts:26

`new Server(serverURL, domain, opts)`

constructor(serverURL: string, domain: string, opts: Options = {});

Parameters

serverURL — string (required)
domain — string (required)
opts — Options (optional) (default: {})

Source: src/federation/server.ts:137

`Server.createForDomain(domain, opts)`

Creates a FederationServer instance based on information from stellar.toml file for a given domain.

If stellar.toml file does not exist for a given domain or it does not contain information about a federation server Promise will reject.

static createForDomain(domain: string, opts: Options = {}): Promise<FederationServer>;

Parameters

domain — string (required) — Domain to get federation server for
opts — Options (optional) (default: {}) — (optional) Options object

Returns

A promise that resolves to the federation record

Throws

Will throw an error if the domain’s stellar.toml file does not contain a federation server field.

Example

StellarSdk.FederationServer.createForDomain('acme.com')
  .then(federationServer => {
    // federationServer.resolveAddress('bob').then(...)
  })
  .catch(error => {
    // stellar.toml does not exist or it does not contain information about federation server.
  });

See also

Stellar.toml doc

Source: src/federation/server.ts:123

`Server.resolve(value, opts)`

A helper method for handling user inputs that contain destination value. It accepts two types of values:

For Stellar address (ex. bob*stellar.org) it splits Stellar address and then tries to find information about federation server in stellar.toml file for a given domain. It returns a Promise which resolves if federation server exists and user has been found and rejects in all other cases.
For Account ID (ex. GB5XVAABEQMY63WTHDQ5RXADGYF345VWMNPTN2GFUDZT57D57ZQTJ7PS) it returns a Promise which resolves if Account ID is valid and rejects in all other cases. Please note that this method does not check if the account actually exists in a ledger.

static resolve(value: string, opts: Options = {}): Promise<Record>;

Parameters

value — string (required) — Stellar Address (ex. bob*stellar.org)
opts — Options (optional) (default: {}) — (optional) Options object

Returns

A promise that resolves to the federation record

Throws

Will throw an error if the provided account ID is not a valid Ed25519 public key.

Example

StellarSdk.FederationServer.resolve('bob*stellar.org')
 .then(federationRecord => {
   // {
   //   account_id: 'GB5XVAABEQMY63WTHDQ5RXADGYF345VWMNPTN2GFUDZT57D57ZQTJ7PS',
   //   memo_type: 'id',
   //   memo: 100
   // }
 });

See also

Source: src/federation/server.ts:72

`server.resolveAccountId(accountId)`

Given an account ID, get their federation record if the user was found

resolveAccountId(accountId: string): Promise<Record>;

Parameters

accountId — string (required) — Account ID (ex. GBYNR2QJXLBCBTRN44MRORCMI4YO7FZPFBCNOKTOBCAAFC7KC3LNPRYS)

Returns

A promise that resolves to the federation record

Throws

Will throw an error if the federation server returns an invalid memo value.
Will throw an error if the federation server’s response exceeds the allowed maximum size.
Will throw an error if the server query fails with an improper response.

See also

Federation doc

Source: src/federation/server.ts:194

`server.resolveAddress(address)`

Get the federation record if the user was found for a given Stellar address

resolveAddress(address: string): Promise<Record>;

Parameters

address — string (required) — Stellar address (ex. bob*stellar.org). If FederationServer was instantiated with domain param only username (ex. bob) can be passed.

Returns

A promise that resolves to the federation record

Throws

Will throw an error if the federated address does not contain a domain, or if the server object was not instantiated with a domain parameter

See also

Federation doc

Source: src/federation/server.ts:166

`server.resolveTransactionId(transactionId)`

Given a transactionId, get the federation record if the sender of the transaction was found

resolveTransactionId(transactionId: string): Promise<Record>;

Parameters

transactionId — string (required) — Transaction ID (ex. 3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889)

Returns

A promise that resolves to the federation record

Throws

Will throw an error if the federation server returns an invalid memo value.
Will throw an error if the federation server’s response exceeds the allowed maximum size.
Will throw an error if the server query fails with an improper response.

See also

Federation doc

Source: src/federation/server.ts:211

Types

Federation.Api.Options

Options for configuring connections to federation servers. You can also use Config class to set this globally.

interface Options {
  allowHttp?: boolean;
  timeout?: number;
}

Source: src/federation/api.ts:25

`options.allowHttp`

Allow connecting to http servers, default: false. This must be set to false in production deployments!

allowHttp?: boolean;

Source: src/federation/api.ts:29

`options.timeout`

Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue.

timeout?: number;

Source: src/federation/api.ts:33

Federation.Api.Record

Record returned from a federation server.

interface Record {
  account_id: string;
  memo?: string;
  memo_type?: string;
}

Source: src/federation/api.ts:7

`record.account_id`

The Stellar public key resolved from the federation lookup

account_id: string;

Source: src/federation/api.ts:11

`record.memo`

The memo value, if any, required to send payments to this user

memo?: string;

Source: src/federation/api.ts:19

`record.memo_type`

The type of memo, if any, required to send payments to this user

memo_type?: string;

Source: src/federation/api.ts:15