Utils

Utils

Methods

(static) buildChallengeTx(serverKeypair, clientAccountID, homeDomain, timeoutopt, networkPassphrase) → {string}

Returns a valid SEP0010 challenge transaction which you can use for Stellar Web Authentication.

Source:
See:
Parameters:
Name Type Attributes Default Description
serverKeypair Keypair

Keypair for server's signing account.

clientAccountID string

The stellar account that the wallet wishes to authenticate with the server.

homeDomain string

The fully qualified domain name of the service requiring authentication

timeout number <optional>
300

Challenge duration (default to 5 minutes).

networkPassphrase string

The network passphrase. If you pass this argument then timeout is required.

Returns:
Type:
string

A base64 encoded string of the raw TransactionEnvelope xdr struct for the transaction.

Example
import { Utils, Keypair, Networks }  from 'stellar-sdk'

let serverKeyPair = Keypair.fromSecret("server-secret")
let challenge = Utils.buildChallengeTx(serverKeyPair, "client-stellar-account-id", "SDF", 300, Networks.TESTNET)

(static) gatherTxSigners(transaction, signers) → {Array.<string>}

gatherTxSigners checks if a transaction has been signed by one or more of the given signers, returning a list of non-repeated signers that were found to have signed the given transaction.

Source:
Parameters:
Name Type Description
transaction Transaction

the signed transaction.

signers Array.<string>

The signers public keys.

Returns:
Type:
Array.<string>

a list of signers that were found to have signed the transaction.

Example
let keypair1 = Keypair.random();
let keypair2 = Keypair.random();
const account = new StellarSdk.Account(keypair1.publicKey(), "-1");

const transaction = new TransactionBuilder(account, { fee: 100 })
   .setTimeout(30)
   .build();

transaction.sign(keypair1, keypair2)
Utils.gatherTxSigners(transaction, [keypair1.publicKey(), keypair2.publicKey()])

(static) readChallengeTx(challengeTx, serverAccountID, networkPassphrase, homeDomainopt) → {Transaction|string}

readChallengeTx reads a SEP 10 challenge transaction and returns the decoded transaction and client account ID contained within.

It also verifies that the transaction has been signed by the server.

It does not verify that the transaction has been signed by the client or that any signatures other than the server's on the transaction are valid. Use one of the following functions to completely verify the transaction:

  • verifyChallengeTxThreshold
  • verifyChallengeTxSigners
Source:
See:
Parameters:
Name Type Attributes Description
challengeTx string

SEP0010 challenge transaction in base64.

serverAccountID string

The server's stellar account (public key).

networkPassphrase string

The network passphrase, e.g.: 'Test SDF Network ; September 2015'.

homeDomain string <optional>

The field is reserved for future use and not used.

Returns:
Type:
Transaction | string

The actual submited transaction and the stellar public key (master key) used to sign the Manage Data operation.

(static) validateTimebounds(transaction) → {boolean}

Verifies if the current date is within the transaction's timebonds

Source:
Parameters:
Name Type Description
transaction Transaction

the transaction whose timebonds will be validated.

Returns:
Type:
boolean

returns true if the current time is within the transaction's [minTime, maxTime] range.

(static) verifyChallengeTxSigners(challengeTx, serverAccountID, networkPassphrase, signers) → {Array.<string>}

verifyChallengeTxSigners verifies that for a SEP 10 challenge transaction all signatures on the transaction are accounted for. A transaction is verified if it is signed by the server account, and all other signatures match a signer that has been provided as an argument (as the accountIDs list). Additional signers can be provided that do not have a signature, but all signatures must be matched to a signer (accountIDs) for verification to succeed. If verification succeeds, a list of signers that were found is returned, not including the server account ID.

Signers that are not prefixed as an address/account ID strkey (G...) will be ignored.

Errors will be raised if:

  • The transaction is invalid according to ReadChallengeTx.
  • No client signatures are found on the transaction.
  • One or more signatures in the transaction are not identifiable as the server account or one of the signers provided in the arguments.
Source:
See:
Parameters:
Name Type Description
challengeTx string

SEP0010 challenge transaction in base64.

serverAccountID string

The server's stellar account (public key).

networkPassphrase string

The network passphrase, e.g.: 'Test SDF Network ; September 2015'.

signers Array.<string>

The signers public keys. This list should contain the public keys for all signers that have signed the transaction.

Returns:
Type:
Array.<string>

The list of signers public keys that have signed the transaction, excluding the server account ID.

Example
import { Networks, TransactionBuilder, Utils }  from 'stellar-sdk';

const serverKP = Keypair.random();
const clientKP1 = Keypair.random();
const clientKP2 = Keypair.random();

// Challenge, possibly built in the server side
const challenge = Utils.buildChallengeTx(
  serverKP,
  clientKP1.publicKey(),
  "SDF",
  300,
  Networks.TESTNET
);

// clock.tick(200);  // Simulates a 200 ms delay when communicating from server to client

// Transaction gathered from a challenge, possibly from the client side
const transaction = TransactionBuilder.fromXDR(challenge, Networks.TESTNET);
transaction.sign(clientKP1, clientKP2);
const signedChallenge = transaction
        .toEnvelope()
        .toXDR("base64")
        .toString();

// The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
Utils.verifyChallengeTxSigners(signedChallenge, serverKP.publicKey(), Networks.TESTNET, threshold, [clientKP1.publicKey(), clientKP2.publicKey()]);

(static) verifyChallengeTxThreshold(challengeTx, serverAccountID, networkPassphrase, threshold, signerSummary) → {Array.<string>}

verifyChallengeTxThreshold verifies that for a SEP 10 challenge transaction all signatures on the transaction are accounted for and that the signatures meet a threshold on an account. A transaction is verified if it is signed by the server account, and all other signatures match a signer that has been provided as an argument, and those signatures meet a threshold on the account.

Signers that are not prefixed as an address/account ID strkey (G...) will be ignored.

Errors will be raised if:

  • The transaction is invalid according to ReadChallengeTx.
  • No client signatures are found on the transaction.
  • One or more signatures in the transaction are not identifiable as the server account or one of the signers provided in the arguments.
  • The signatures are all valid but do not meet the threshold.
Source:
See:
Parameters:
Name Type Description
challengeTx string

SEP0010 challenge transaction in base64.

serverAccountID string

The server's stellar account (public key).

networkPassphrase string

The network passphrase, e.g.: 'Test SDF Network ; September 2015'.

threshold number

The required signatures threshold for verifying this transaction.

signerSummary Array.<ServerApi.AccountRecordSigners>

a map of all authorized signers to their weights. It's used to validate if the transaction signatures have met the given threshold.

Returns:
Type:
Array.<string>

The list of signers public keys that have signed the transaction, excluding the server account ID, given that the threshold was met.

Example
import { Networks, TransactionBuilder, Utils }  from 'stellar-sdk';

const serverKP = Keypair.random();
const clientKP1 = Keypair.random();
const clientKP2 = Keypair.random();

// Challenge, possibly built in the server side
const challenge = Utils.buildChallengeTx(
  serverKP,
  clientKP1.publicKey(),
  "SDF",
  300,
  Networks.TESTNET
);

// clock.tick(200);  // Simulates a 200 ms delay when communicating from server to client

// Transaction gathered from a challenge, possibly from the client side
const transaction = TransactionBuilder.fromXDR(challenge, Networks.TESTNET);
transaction.sign(clientKP1, clientKP2);
const signedChallenge = transaction
        .toEnvelope()
        .toXDR("base64")
        .toString();

// Defining the threshold and signerSummary
const threshold = 3;
const signerSummary = [
   {
     key: this.clientKP1.publicKey(),
     weight: 1,
   },
   {
     key: this.clientKP2.publicKey(),
     weight: 2,
   },
 ];

// The result below should be equal to [clientKP1.publicKey(), clientKP2.publicKey()]
Utils.verifyChallengeTxThreshold(signedChallenge, serverKP.publicKey(), Networks.TESTNET, threshold, signerSummary);

(static) verifyTxSignedBy(transaction, accountID) → {boolean}

Verifies if a transaction was signed by the given account id.

Source:
Parameters:
Name Type Description
transaction Transaction
accountID string
Returns:
Type:
boolean

.

Example
let keypair = Keypair.random();
const account = new StellarSdk.Account(keypair.publicKey(), "-1");

const transaction = new TransactionBuilder(account, { fee: 100 })
   .setTimeout(30)
   .build();

transaction.sign(keypair)
Utils.verifyTxSignedBy(transaction, keypair.publicKey())