Stellar Network - Stellar Developer Docs

This guide is available on four different programming languages: Typescript, Kotlin, Flutter (Dart) and Swift. You can change the shown version on each page via the buttons above.

In the previous section we learned how to create a wallet and a Stellar object that provides a connection to Horizon. In this section, we will look at the usages of this class.

Accounts

The most basic entity on the Stellar network is an account. Let’s look into AccountService that provides the capability to work with accounts:

Kotlin
TypeScript
Flutter
Swift

val account = wallet.stellar().account()

let account = wal.stellar().account();

var account = wallet.stellar().account();

let account = wallet.stellar.account

Now we can create a keypair:

Kotlin
TypeScript
Flutter
Swift

val accountKeyPair = account.createKeyPair()

let accountKeyPair = account.createKeypair();

var accountKeyPair = account.createKeyPair();

let accountKeyPair = account.createKeyPair()

If using react-native, createKeypair won’t work. Instead use the helper method createKeypairFromRandom like this:

import * as Random from "expo-crypto";
const rand = Random.randomBytes(32);
const kp = account.createKeypairFromRandom(Buffer.from(rand));

Build Transaction

The transaction builder allows you to create various transactions that can be signed and submitted to the Stellar network. Some transactions can be sponsored.

Building Basic Transactions

First, let’s look into building basic transactions.

Create Account

The create account transaction activates/creates an account with a starting balance of XLM (1 XLM by default).

Kotlin
TypeScript
Flutter
Swift

suspend fun createAccount(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).createAccount(destinationAccountKeyPair).build()
}

const txBuilder = await stellar.transaction({
  sourceAddress: sourceAccountKeyPair,
});
const tx = txBuilder.createAccount(destinationAccountKeyPair).build();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.createAccount(destinationAccountKeyPair).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.createAccount(newAccount: destinationAccountKeyPair).build()

Modify Account

You can lock the master key of the account by setting its weight to 0. Use caution when locking the account’s master key. Make sure you have set the correct signers and weights. Otherwise, you will lock the account irreversibly.

Kotlin
TypeScript
Flutter
Swift

suspend fun lockMasterKey(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).lockAccountMasterKey().build()
}

const txBuilder = await stellar.transaction({
  sourceAddress: sourceAccountKeyPair,
});

const tx = txBuilder.lockAccountMasterKey().build();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.lockAccountMasterKey().build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.lockAccountMasterKey().build()

Add a new signer to the account. Use caution when adding new signers and make sure you set the correct signer weight. Otherwise, you will lock the account irreversibly.

Kotlin
TypeScript
Flutter
Swift

val newSignerKeyPair = account.createKeyPair()

suspend fun addSigner(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).addAccountSigner(newSignerKeyPair, 10).build()
}

const newSignerKeyPair = account.createKeypair();

const tx = txBuilder.addAccountSigner(newSignerKeyPair, 10).build();

var newSignerKeyPair = account.createKeyPair();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.addAccountSigner(newSignerKeyPair, 10).build();

let newSignerKeyPair = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.addAccountSigner(signerAddress: newSignerKeyPair, signerWeight: 10).build()

Remove a signer from the account.

Kotlin
TypeScript
Flutter
Swift

suspend fun removeSigner(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).removeAccountSigner(newSignerKeyPair).build()
}

const tx = txBuilder.removeAccountSigner(newSignerKeyPair).build();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.removeAccountSigner(newSignerKeyPair).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.removeAccountSigner(signerAddress: newSignerKeyPair).build()

Modify account thresholds (useful when multiple signers are assigned to the account). This allows you to restrict access to certain operations when the limit is not reached.

Kotlin
TypeScript
Flutter
Swift

suspend fun setThreshold(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).setThreshold(low = 1, medium = 10, high = 30).build()
}

const tx = txBuilder.setThreshold({ low: 1, medium: 10, high: 30 }).build();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.setThreshold(low: 1, medium: 10, high: 20).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.setThreshold(low: 1, medium: 10, high: 20).build()

Modify Assets (Trustlines)

Add an asset (trustline) to the account. This allows the account to receive transfers of the asset.

Kotlin
TypeScript
Flutter
Swift

val asset = IssuedAssetId("USDC", "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5")

suspend fun addAsset(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).addAssetSupport(asset).build()
}

const asset = new IssuedAssetId(
  "USDC",
  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
);

const tx = txBuilder.addAssetSupport(asset).build();

var asset = IssuedAssetId(
        code: "USDC",
        issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5");

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.addAssetSupport(asset).build();

let asset = try IssuedAssetId(
    code: "USDC",
    issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5")

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.addAssetSupport(asset: asset).build()

Remove an asset from the account (the asset’s balance must be 0).

Kotlin
TypeScript
Flutter
Swift

suspend fun removeAsset(): Transaction {
  return stellar.transaction(sourceAccountKeyPair).removeAssetSupport(asset).build()
}

const tx = txBuilder.removeAssetSupport(asset).build();

var txBuilder = await stellar.transaction(sourceAccountKeyPair);
var tx = txBuilder.removeAssetSupport(asset).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let tx = try txBuilder.removeAssetSupport(asset: asset).build()

Swap

Exchange an account’s asset for a different asset. The account must have a trustline for the destination asset. A swap is filled at whatever rate the network can find when the transaction is applied, which may differ from the rate you quoted to the user. The minimum destination amount (destMin) is the slippage limit that protects against that: it is the least amount of the destination asset the account is willing to receive for the amount it sends. If the swap cannot deliver at least that much, the transaction fails instead of executing at a worse rate. Derive it from a current quote minus the slippage tolerance you are willing to accept.

TypeScript
Flutter
Swift

const txBuilder = await stellar.transaction({
  sourceAddress: sourceKp,
});
const usdcAsset = new IssuedAssetId(
  "USDC",
  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
);
// Send 0.1 XLM and accept no less than 0.025 USDC back
const txn = txBuilder
  .swap(new NativeAssetId(), usdcAsset, ".1", ".025")
  .build();

var txBuilder = await stellar.transaction(sourceKp);

final usdcAsset = IssuedAssetId(
    code: 'USDC',
    issuer: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
);

// Send 0.1 XLM and accept no less than 0.025 USDC back
var txn = txBuilder.swap(
    fromAsset: NativeAssetId(),
    toAsset: usdcAsset,
    amount: "0.1",
    destMin: "0.025",
  ).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceKp)

let usdcAsset = try IssuedAssetId(
    code: "USDC",
    issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5")

// Send 0.1 XLM and accept no less than 0.025 USDC back
let txn = try txBuilder.swap(fromAsset: NativeAssetId(),
                             toAsset: usdcAsset,
                             amount: 0.1,
                             destMin: 0.025).build()

Path Pay

Send one asset from the source account and receive a different asset in the destination account. Like a swap, a path payment is filled at the rate available when the transaction is applied, so it takes a slippage limit. Which limit depends on which side of the payment is fixed:

When you fix the amount to send (sendAmount), pass destMin: the least amount of the destination asset the recipient must receive.
When you fix the amount to deliver (destAmount), pass sendMax: the maximum amount of the send asset the source account is willing to spend.

If the network cannot fill the payment within that limit, the transaction fails instead of executing at a worse rate. Derive the limit from a current quote plus or minus the slippage tolerance you are willing to accept.

TypeScript
Flutter
Swift

const txBuilder = await stellar.transaction({
  sourceAddress: sourceKp,
});
const usdcAsset = new IssuedAssetId(
  "USDC",
  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
);
// Send 5 XLM; the recipient must receive at least 1.25 USDC
const txn = txBuilder
  .pathPay({
    destinationAddress: receivingKp.publicKey,
    sendAsset: new NativeAssetId(),
    destAsset: usdcAsset,
    sendAmount: "5",
    destMin: "1.25",
  })
  .build();

var txBuilder = await stellar.transaction(sourceKp);

final usdcAsset = IssuedAssetId(
    code: 'USDC',
    issuer: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5',
);

// Send 5 XLM; the recipient must receive at least 1.25 USDC
var txn = txBuilder.pathPay(
    destinationAddress: receivingKp.address,
    sendAsset: NativeAssetId(),
    destinationAsset: usdcAsset,
    sendAmount: "5",
    destMin: "1.25",
  ).build();

let txBuilder = try await stellar.transaction(sourceAddress: sourceKp)

let usdcAsset = try IssuedAssetId(
    code: "USDC",
    issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5")

// Send 5 XLM; the recipient must receive at least 1.25 USDC
let txn = try txBuilder.pathPay(destinationAddress: receivingKp.address,
                                sendAsset: NativeAssetId(),
                                destinationAsset: usdcAsset,
                                sendAmount: 5,
                                destMin: 1.25).build()

To deliver an exact amount of the destination asset instead, pass destAmount together with sendMax:

TypeScript
Flutter
Swift

// Deliver exactly 5 USDC; spend no more than 21 XLM to do it
const txn = txBuilder
  .pathPay({
    destinationAddress: receivingKp.publicKey,
    sendAsset: new NativeAssetId(),
    destAsset: usdcAsset,
    destAmount: "5",
    sendMax: "21",
  })
  .build();

// Deliver exactly 5 USDC; spend no more than 21 XLM to do it
var txn = txBuilder.pathPay(
    destinationAddress: receivingKp.address,
    sendAsset: NativeAssetId(),
    destinationAsset: usdcAsset,
    destAmount: "5",
    sendMax: "21",
  ).build();

// Deliver exactly 5 USDC; spend no more than 21 XLM to do it
let txn = try txBuilder.pathPay(destinationAddress: receivingKp.address,
                                sendAsset: NativeAssetId(),
                                destinationAsset: usdcAsset,
                                destAmount: 5,
                                sendMax: 21).build()

Set Memo

Set a memo on the transaction. The memo object can be imported from “@stellar/stellar-sdk”.

TypeScript
Flutter
Swift

import { Memo } from "@stellar/stellar-sdk";

const tx = txBuilder.setMemo(new Memo("text", "Memo string")).build();

import 'package:stellar_flutter_sdk/stellar_flutter_sdk.dart' as flutter_sdk;

var memo = flutter_sdk.MemoText("Memo string");
var tx = txBuilder.setMemo(memo).build();

import stellarsdk

let memo = Memo.text("Memo string")
let tx = try txBuilder.setMemo(memo: memo).build()

Account Merge

Merges account into a destination account.

TypeScript
Flutter
Swift

const txBuilder = await stellar.transaction({
  sourceAddress: accountKp,
  baseFee: 1000,
});
const mergeTxn = txBuilder
  .accountMerge(accountKp.publicKey, sourceKp.publicKey)
  .build();

var txBuilder = await stellar.transaction(accountKp, baseFee: 1000);

var mergeTxn = txBuilder.accountMerge(
    destinationAddress: accountKp.address,
    sourceAddress: sourceKp.address,
  ).build();

let txBuilder = try await stellar.transaction(sourceAddress: accountKp,
                                              baseFee: 1000)

let mergeTxn = try txBuilder.accountMerge(destinationAddress: accountKp.address,
                                          sourceAddress: sourceKp.address).build()

Fund Testnet Account

Fund an account on the Stellar test network

TypeScript
Flutter
Swift

wallet.stellar().fundTestnetAccount(accountKp.publicKey);

await wallet.stellar().fundTestNetAccount(accountKp.address);

try await wallet.stellar.fundTestNetAccount(address: accountKp.address)

Building Advanced Transactions

In some cases a private key may not be known prior to forming a transaction. For example, a new account must be funded to exist and the wallet may not have the key for the account so may request the create account transaction to be sponsored by a third party.

Kotlin
TypeScript
Flutter
Swift

// Third-party key that will sponsor creating new account
val externalKeyPair = "MySponsorAddress".toPublicKeyPair()
val newKeyPair = account.createKeyPair()

// Third-party key that will sponsor creating new account
const externalKeyPair = new PublicKeypair.fromPublicKey("GC5GD...");
const newKeyPair = account.createKeypair();

// Third-party key that will sponsor creating new account
var externalKeyPair = PublicKeyPair.fromAccountId("GC5GD...");
var newKeyPair = account.createKeyPair();

// Third-party key that will sponsor creating new account
let externalKeyPair = try PublicKeyPair(accountId: "GC5GD...")
let newKeyPair = account.createKeyPair()

First, the account must be created.

Kotlin
TypeScript
Flutter
Swift

suspend fun makeCreateTx(): Transaction {
  return stellar.transaction(externalKeyPair).createAccount(newKeyPair).build()
}

const createTxn = txBuilder.createAccount(newKeyPair).build();

var txBuilder = await stellar.transaction(externalKeyPair);
var createTxn = txBuilder.createAccount(newKeyPair).build();

let txBuilder = try await stellar.transaction(sourceAddress: externalKeyPair)
let createTxn = try txBuilder.createAccount(newAccount: newKeyPair).build()

This transaction must be sent to external signer (holder of externalKeyPair) to be signed.

Kotlin
TypeScript
Flutter
Swift

suspend fun remoteSignTransaction(transaction: Transaction) {
  val xdrString = transaction.toEnvelopeXdrBase64()
  // Send xdr encoded transaction to your backend server to sign
  val xdrStringFromBackend = sendTransactionToBackend(xdrString)

  // Decode xdr to get the signed transaction
  val signedTransaction = stellar.decodeTransaction(xdrStringFromBackend)
}

const xdrString = createTxn.toXDR();
// Send xdr encoded transaction to your backend server to sign
const xdrStringFromBackend = await sendTransactionToBackend(xdrString);

// Decode xdr to get the signed transaction
const signedTransaction = stellar.decodeTransaction(xdrStringFromBackend);

var xdrString = createTxn.toEnvelopeXdrBase64();

// Send xdr encoded transaction to your backend server to sign
var xdrStringFromBackend = await sendTransactionToBackend(xdrString);

// Decode xdr to get the signed transaction
var signedTransaction = stellar.decodeTransaction(xdrStringFromBackend);

let xdrString = createTxn.toEnvelopeXdrBase64()

// Send xdr encoded transaction to your backend server to sign
let xdrStringFromBackend = await sendTransactionToBackend(xdrString)

// Decode xdr to get the signed transaction
let signedTransaction = stellar.decodeTransaction(xdr: xdrStringFromBackend)

You can read more about passing XDR transaction to the server in the chapter below.

Signed transaction can be submitted by the wallet.

Kotlin
TypeScript
Flutter
Swift

suspend fun submitCreateTx(signedCreateTx: Transaction) {
  wallet.stellar().submitTransaction(signedCreateTx)
}

await wallet.stellar().submitTransaction(signedTransaction);

bool success = await stellar.submitTransaction(signedTransaction);

try await stellar.submitTransaction(signedTransaction: signedTransaction)

Now, after the account is created, it can perform operations. For example, we can disable the master keypair and replace it with a new one (let’s call it the device keypair) atomically in one transaction:

Kotlin
TypeScript
Flutter
Swift

suspend fun addDeviceKeyPair() {
  val deviceKeyPair = account.createKeyPair()

  val modifyAccountTransaction =
    stellar
      .transaction(newKeyPair)
      .addAccountSigner(
        deviceKeyPair,
        signerWeight = 1,
      )
      .lockAccountMasterKey()
      .build()
      .sign(newKeyPair)

  wallet.stellar().submitTransaction(modifyAccountTransaction)
}

const deviceKeyPair = account.createKeypair();

const txBuilder = await stellar.transaction({ sourceAddress: newKeyPair });
const modifyAccountTransaction = txBuilder
  .addAccountSigner(deviceKeyPair, 1)
  .lockAccountMasterKey()
  .build();
newKeyPair.sign(modifyAccountTransaction);

await wallet.stellar().submitTransaction(modifyAccountTransaction);

var deviceKeyPair = account.createKeyPair();

var txBuilder = await stellar.transaction(newKeyPair);
var modifyAccountTransaction = txBuilder
    .addAccountSigner(deviceKeyPair, 1)
    .lockAccountMasterKey()
    .build();

stellar.sign(modifyAccountTransaction, newKeyPair);

bool success = await stellar.submitTransaction(modifyAccountTransaction);

let deviceKeyPair = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: newKeyPair)

let modifyAccountTransaction = try txBuilder
    .addAccountSigner(signerAddress: deviceKeyPair, signerWeight: 1)
    .lockAccountMasterKey()
    .build()

stellar.sign(tx: modifyAccountTransaction,
             keyPair: newKeyPair)

try await stellar.submitTransaction(signedTransaction: modifyAccountTransaction)

Adding an Operation

Add a custom Operation to a transaction. This can be any Operation supported by the Stellar network. The Operation object can be imported from “@stellar/stellar-sdk”.

TypeScript
Flutter
Swift

import { Operation } from "@stellar/stellar-sdk";

const txBuilder = await stellar.transaction({
  sourceAddress: sourceAccountKeyPair,
});
const tx = txBuilder.addOperation(
  Operation.manageData({
    name: "web_auth_domain",
    value: new URL(authServer).hostname,
    source: sourceAccountKeyPair,
  }),
);

import 'package:stellar_flutter_sdk/stellar_flutter_sdk.dart' as flutter_sdk;

var txBuilder = await stellar.transaction(sourceAccountKeyPair);

var key = "web_auth_domain";
var value = "https://testanchor.stellar.org";
var valueBytes = Uint8List.fromList(value.codeUnits);

var manageDataOperation = flutter_sdk.ManageDataOperationBuilder(
    key,
    valueBytes,
  ).build();

var tx = txBuilder.addOperation(
    manageDataOperation,
  ).build();

import stellarsdk

let txBuilder = try await stellar.transaction(sourceAddress: sourceAccountKeyPair)
let key = "web_auth_domain"
let value = "testanchor.stellar.org"
let manageDataOperation = ManageDataOperation(sourceAccountId: sourceAccountKeyPair.address,
                                              name: key,
                                              data: value.data(using: .utf8))

let tx = try txBuilder.addOperation(operation: manageDataOperation).build()

Sponsoring Transactions

Some operations, that modify account reserves can be sponsored. For sponsored operations, the sponsoring account will be paying for the reserves instead of the account that being sponsored. This allows you to do some operations, even if account doesn’t have enough funds to perform such operations. To sponsor a transaction, simply start a sponsoring block (Kotlin), or simply create a building function (describing which operations are to be sponsored) and pass it to the sponsoring method (TypeScript):

Kotlin
TypeScript
Flutter
Swift

suspend fun sponsorOperation() {
  val transaction =
    stellar
      .transaction(sponsoredKeyPair)
      .sponsoring(sponsorKeyPair) { addAssetSupport(asset) }
      .build()

  transaction.sign(sponsorKeyPair).sign(sponsoredKeyPair)
}

const txBuilder = await stellar.transaction({
  sourceAddress: sponsoredKeyPair,
});

const buildingFunction = (bldr) => bldr.addAssetSupport(asset);
const transaction = txBuilder
  .sponsoring(sponsorKeyPair, buildingFunction)
  .build();

sponsoredKeyPair.sign(transaction);
sponsorKeyPair.sign(transaction);

var txBuilder = await stellar.transaction(sponsoredKeyPair);
var transaction = txBuilder
    .sponsoring(sponsorKeyPair, (builder) => builder.addAssetSupport(asset))
    .build();

stellar.sign(transaction, sponsorKeyPair);
stellar.sign(transaction, sponsoredKeyPair);

let txBuilder = try await stellar.transaction(sourceAddress: sponsoredKeyPair)
let transaction = try txBuilder.sponsoring(
    sponsorAccount: sponsorKeyPair,
    buildingFunction:{ (builder) in builder.addAssetSupport(asset: asset)}).build()

stellar.sign(tx: transaction, keyPair: sponsorKeyPair)
stellar.sign(tx: transaction, keyPair: sponsoredKeyPair)

Only some operations can be sponsored, and a sponsoring block (Kotlin) / builder (TypeScript) has a slightly different set of functions available compared to the regular TransactionBuilder. Note, that a transaction must be signed by both the sponsor account (sponsoringKeyPair) and the account being sponsored (sponsoredKeyPair).

Sponsoring Account Creation

One of the things that can be done via sponsoring is to create an account with a 0 starting balance. This account creation can be created by simply writing:

Kotlin
TypeScript
Flutter
Swift

suspend fun sponsorAccountCreation() {
  val newKeyPair = account.createKeyPair()

  val transaction =
    stellar
      .transaction(sponsorKeyPair)
      .sponsoring(sponsorKeyPair, sponsoredAccount = newKeyPair) { createAccount(newKeyPair) }
      .build()

  transaction.sign(sponsorKeyPair).sign(newKeyPair)
}

const txBuilder = await stellar.transaction({ sourceAddress: sponsorKeyPair });

const newKeyPair = account.createKeypair();

const buildingFunction = (bldr) => bldr.createAccount(newKeyPair);
const transaction = txBuilder
  .sponsoring(sponsorKeyPair, buildingFunction, newKeyPair)
  .build();

newKeyPair.sign(transaction);
sponsorKeyPair.sign(transaction);

var newKeyPair = account.createKeyPair();

var txBuilder = await stellar.transaction(sponsorKeyPair);
var transaction = txBuilder
    .sponsoring(sponsorKeyPair, sponsoredAccount: newKeyPair,
        (builder) => builder.createAccount(newKeyPair))
    .build();

stellar.sign(transaction, sponsorKeyPair);
stellar.sign(transaction, newKeyPair);

let newKeyPair = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: sponsorKeyPair)
let transaction = try txBuilder.sponsoring(
    sponsorAccount: sponsorKeyPair,
    buildingFunction:{ (builder) in builder.createAccount(newAccount: newKeyPair)},
    sponsoredAccount: newKeyPair).build()

stellar.sign(tx: transaction, keyPair: sponsorKeyPair)
stellar.sign(tx: transaction, keyPair: newKeyPair)

Note how in the first example the transaction source account is set to sponsoredKeyPair. Due to this, we did not need to pass a sponsored account value to the sponsoring block (Kotlin) / method (TypeScript). Since when ommitted, the sponsored account defaults to the transaction source account (sponsoredKeyPair). However, this time, the sponsored account (freshly created newKeyPair) is different from the transaction source account. Therefore, it’s necessary to specify it. Otherwise, the transaction will contain a malformed operation. As before, the transaction must be signed by both keys.

Sponsoring Account Creation and Modification

If you want to create an account and modify it in one transaction, it’s possible to do so with passing a sponsoredAccount optional argument to the sponsored block (Kotlin) / sponsoring method (TypeScript) (newKeyPair below). If this argument is present, all operations inside the sponsored block will be sourced by this sponsoredAccount. (Except account creation, which is always sourced by the sponsor).

Kotlin
TypeScript
Flutter
Swift

suspend fun sponsorAccountCreationAndModification() {
  val newKeyPair = account.createKeyPair()
  val replaceWith = account.createKeyPair()

  val transaction =
    stellar
        .transaction(sponsorKeyPair)
        .sponsoring(sponsorKeyPair, newKeyPair) {
          createAccount(newKeyPair)
          // source account for below operations will be newKeyPair
          addAccountSigner(replaceWith, 1)
          lockAccountMasterKey()
        }
        .build()

  transaction.sign(sponsorKeyPair).sign(newKeyPair)
}

const txBuilder = await stellar.transaction({ sourceAddress: sponsorKeyPair });

const newKeyPair = account.createKeypair();
const replaceWith = account.createKeypair();

const buildingFunction = (bldr) =>
  bldr
    .createAccount(newKeyPair)
    // source account for below operations will be newKeyPair
    .addAccountSigner(replaceWith, 1)
    .lockAccountMasterKey();

const transaction = txBuilder
  .sponsoring(sponsorKeyPair, buildingFunction, newKeyPair)
  .build();

newKeyPair.sign(transaction);
sponsorKeyPair.sign(transaction);

var newKeyPair = account.createKeyPair();
var replaceWith = account.createKeyPair();

var txBuilder = await stellar.transaction(sponsorKeyPair);
var transaction = txBuilder
    .sponsoring(
    sponsorKeyPair,
    sponsoredAccount: newKeyPair,
        (builder) => builder
        .createAccount(newKeyPair)
        .addAccountSigner(replaceWith, 1)
        .lockAccountMasterKey())
    .build();

stellar.sign(transaction, sponsorKeyPair);
stellar.sign(transaction, newKeyPair);

let newKeyPair = account.createKeyPair()
let replaceWith = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: sponsorKeyPair)
let transaction = try txBuilder.sponsoring(
    sponsorAccount: sponsorKeyPair,
    buildingFunction:{ (builder) in builder
            .createAccount(newAccount: newKeyPair)
            .addAccountSigner(signerAddress: replaceWith, signerWeight: 1)
            .lockAccountMasterKey()
    },
    sponsoredAccount: newKeyPair).build()

stellar.sign(tx: transaction, keyPair: sponsorKeyPair)
stellar.sign(tx: transaction, keyPair: newKeyPair)

Fee-Bump Transaction

If you wish to modify a newly created account with a 0 balance, it’s also possible to do so via FeeBump. It can be combined with a sponsoring block (Kotlin) / method (TypeScript) to achieve the same result as in the example above. However, with FeeBump it’s also possible to add more operations (that don’t require sponsoring), such as a transfer. First, let’s create a transaction that will replace the master key of an account with a new keypair.

Kotlin
TypeScript
Flutter
Swift

val replaceWith = account.createKeyPair()

val transaction =
  stellar
    .transaction(sponsoredKeyPair)
    .sponsoring(sponsorKeyPair) {
      lockAccountMasterKey()
      addAccountSigner(replaceWith, signerWeight = 1)
    }
    .build()

const txBuilder = await stellar.transaction({
  sourceAddress: sponsoredKeyPair,
});

const replaceWith = account.createKeypair();

const buildingFunction = (bldr) =>
  bldr.lockAccountMasterKey().addAccountSigner(replaceWith, 1);
const transaction = txBuilder
  .sponsoring(sponsorKeyPair, buildingFunction)
  .build();

var replaceWith = account.createKeyPair();

var txBuilder = await stellar.transaction(sponsoredKeyPair);
var transaction = txBuilder
    .sponsoring(sponsorKeyPair,
        (builder) => builder.lockAccountMasterKey().addAccountSigner(replaceWith, 1))
    .build();

let replaceWith = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: sponsoredKeyPair)
let transaction = try txBuilder.sponsoring(
    sponsorAccount: sponsorKeyPair,
    buildingFunction:{ (builder) in builder
            .lockAccountMasterKey()
            .addAccountSigner(signerAddress: replaceWith, signerWeight: 1)
    }).build()

Second, sign transaction with both keys.

Kotlin
TypeScript
Flutter
Swift

transaction.sign(sponsoredKeyPair).sign(sponsorKeyPair)

sponsorKeyPair.sign(transaction);
sponsoredKeyPair.sign(transaction);

stellar.sign(transaction, sponsorKeyPair);
stellar.sign(transaction, sponsoredKeyPair);

stellar.sign(tx: transaction, keyPair: sponsorKeyPair)
stellar.sign(tx: transaction, keyPair: sponsoredKeyPair)

Next, create a fee bump, targeting the transaction.

Kotlin
TypeScript
Flutter
Swift

val feeBump = stellar.makeFeeBump(sponsorKeyPair, transaction)
feeBump.sign(sponsorKeyPair)

const feeBump = stellar.makeFeeBump({
  feeAddress: sponsorKeyPair,
  transaction,
});
sponsorKeyPair.sign(feeBump);

var feeBump = stellar.makeFeeBump(sponsorKeyPair, transaction);
stellar.sign(feeBump, sponsorKeyPair);

let feeBump = try stellar.makeFeeBump(feeAddress: sponsorKeyPair,
                                      transaction: transaction)
stellar.sign(tx: transaction, keyPair: sponsorKeyPair)

Finally, submit a fee-bump transaction. Executing this transaction will be fully covered by the sponsorKeyPair and sponsoredKeyPair and may not even have any XLM funds on its account.

Kotlin
TypeScript
Flutter
Swift

wallet.stellar().submitTransaction(feeBump)

await wallet.stellar().submitTransaction(feeBump);

bool success = await stellar.submitTransaction(feeBump);

try await stellar.submitTransaction(signedFeeBumpTransaction: feeBump)

Using XDR to Send Transaction Data

Note, that a wallet may not have a signing key for sponsorKeyPair. In that case, it’s necessary to convert the transaction to XDR, send it to the server, containing sponsorKey and return the signed transaction back to the wallet. Let’s use the previous example of sponsoring account creation, but this time with the sponsor key being unknown to the wallet. The first step is to define the public key of the sponsor keypair:

Kotlin
TypeScript
Flutter
Swift

val sponsorKeyPair = "SponsorAddress".toPublicKeyPair()

const sponsorKeyPair = new PublicKeypair.fromPublicKey("GC5GD...");

var sponsorKeyPair = PublicKeyPair.fromAccountId("GC5GD...");

let sponsorKeyPair = try PublicKeyPair(accountId: "GC5GD...")

Next, create an account in the same manner as before and sign it with newKeyPair. This time, convert the transaction to XDR:

Kotlin
TypeScript
Flutter
Swift

suspend fun sponsorAccountCreation(): String {
  val newKeyPair = account.createKeyPair()

  return stellar
    .transaction(sponsorKeyPair)
    .sponsoring(sponsorKeyPair) { createAccount(newKeyPair) }
    .build()
    .sign(newKeyPair)
    .toEnvelopeXdrBase64()
}

const txBuilder = await stellar.transaction({ sourceAddress: sponsorKeyPair });

const newKeyPair = account.createKeypair();

const transaction = txBuilder
  .sponsoring(sponsorKeyPair, (bldr) => bldr.createAccount(newKeyPair))
  .build();
const xdrString = newKeyPair.sign(transaction).toXDR();

var newKeyPair = account.createKeyPair();

var txBuilder = await stellar.transaction(sponsorKeyPair);
var transaction = txBuilder
    .sponsoring(
        sponsorKeyPair, (builder) => builder.createAccount(newKeyPair),
        sponsoredAccount: newKeyPair)
    .build();

stellar.sign(transaction, newKeyPair);

var xdrString = transaction.toEnvelopeXdrBase64();

let newKeyPair = account.createKeyPair()

let txBuilder = try await stellar.transaction(sourceAddress: sponsorKeyPair)
let transaction = try txBuilder.sponsoring(
            sponsorAccount: sponsorKeyPair,
            buildingFunction:{ (builder) in builder.createAccount(newAccount: newKeyPair)},
            sponsoredAccount: newKeyPair).build()

stellar.sign(tx: transaction, keyPair: newKeyPair)

let xdrString = transaction.toEnvelopeXdrBase64()

It can now be sent to the server. On the server, sign it with a private key for the sponsor address:

Kotlin
TypeScript
Flutter
Swift

// On the server
fun signTransaction(xdrString: String): String {
  val sponsorPrivateKey = SigningKeyPair.fromSecret("MySecret")

  val signedTransaction = stellar.decodeTransaction(xdrString).sign(sponsorPrivateKey)

  return signedTransaction.toEnvelopeXdrBase64()
}

// On the server
const sponsorPrivateKey = SigningKeyPair.fromSecret("SD3LH4...");

const signedTransaction = sponsorPrivateKey.sign(
  stellar.decodeTransaction(xdrString),
);

return signedTransaction.toXDR();

String signTransaction(String xdrString) {
  var sponsorPrivateKey = SigningKeyPair.fromSecret("SD3LH4...");

  var transaction = stellar.decodeTransaction(xdrString);
  stellar.sign(transaction, sponsorPrivateKey);

  return transaction.toEnvelopeXdrBase64();
}

internal func signTransaction(xdr:String) throws -> String {
    let sponsorPrivateKey = try SigningKeyPair(secretKey: "SD3LH4...")

    let transactionEnum = stellar.decodeTransaction(xdr: xdr)
    switch transactionEnum {
    case .transaction(let tx):
        stellar.sign(tx: tx, keyPair: sponsorPrivateKey)
        return tx.toEnvelopeXdrBase64()
    case .feeBumpTransaction(let feeBumpTx):
        stellar.sign(feeBumpTx: feeBumpTx, keyPair: sponsorPrivateKey)
        return feeBumpTx.toEnvelopeXdrBase64()
    case .invalidXdrErr:
        throw ValidationError.invalidArgument(message: "invalid xdr")
    }
}

When the client receives the fully signed transaction, it can be decoded and sent to the Stellar network:

Kotlin
TypeScript
Flutter
Swift

suspend fun recoverSigned(xdrString: String) {
  val signedTransaction = stellar.decodeTransaction(xdrString)

  stellar.submitTransaction(signedTransaction)
}

const signedTransaction = stellar.decodeTransaction(xdrString);

await wallet.stellar().submitTransaction(signedTransaction);

var signedTransaction = stellar.decodeTransaction(xdrStringFromBackend);

bool success = await stellar.submitTransaction(signedTransaction);

let signedTransactionEnum = stellar.decodeTransaction(xdr: xdrStringFromBackend)

switch signedTransactionEnum {
case .transaction(let tx):
    try await stellar.submitTransaction(signedTransaction: tx)
case .feeBumpTransaction(let feeBumpTx):
    try await stellar.submitTransaction(signedFeeBumpTransaction: feeBumpTx)
case .invalidXdrErr:
    throw ValidationError.invalidArgument(message: "invalid xdr")
}

Submit Transaction

It’s strongly recommended to use the wallet SDK transaction submission functions instead of Horizon alternatives. The wallet SDK gracefully handles timeout and out-of-fee exceptions.

Finally, let’s submit a signed transaction to the Stellar network. Note that a sponsored transaction must be signed by both the account and the sponsor. The transaction is automatically re-submitted on the Horizon 504 error (timeout), which indicates a sudden network activity increase.

Kotlin
TypeScript
Flutter
Swift

suspend fun signAndSubmit() {
  val signedTxn = createAccount().sign(sourceAccountKeyPair)
  wallet.stellar().submitTransaction(signedTxn)
}

const signedTxn = transaction.sign(sourceAccountKeyPair);
await wallet.stellar().submitTransaction(signedTxn);

stellar.sign(transaction, sourceAccountKeyPair);
bool success = await stellar.submitTransaction(transaction);

stellar.sign(tx: transaction, keyPair: sourceAccountKeyPair)
try await stellar.submitTransaction(signedTransaction: transaction)

However, the method above doesn’t handle fee surge pricing in the network gracefully. If the required fee for a transaction to be included in the ledger becomes too high and transaction expires before making it into the ledger, this method will throw an exception. So, instead, the alternative approach is to:

Kotlin
TypeScript
Flutter
Swift

suspend fun submitWithFeeIncrease() {
  wallet.stellar().submitWithFeeIncrease(sourceAccountKeyPair, Duration.ofSeconds(30), 100u) {
    this.createAccount(destinationAccountKeyPair)
  }
}

const buildingFunction = (builder) =>
  builder.transfer(kp.publicKey, new NativeAssetId(), "2");

await stellar.submitWithFeeIncrease({
  sourceAddress: kp,
  timeout: 30,
  baseFeeIncrease: 100,
  buildingFunction,
});

bool success = await stellar.submitWithFeeIncrease(
    sourceAddress: sourceAccountKeyPair,
    timeout: const Duration(seconds: 30),
    baseFeeIncrease: 100,
    maxBaseFee: 2000,
    buildingFunction: (builder) =>
    builder.transfer(destinationAccountKeyPair.address, NativeAssetId(), "10.0"));

try await stellar.submitWithFeeIncrease(
  sourceAddress: sourceAccountKeyPair,
  timeout: 30,
  baseFeeIncrease: 100,
  maxBaseFee: 2000,
  buildingFunction: {
      (builder) in try! builder
          .transfer(destinationAddress: destinationAccountKeyPair.address,
                    assetId: NativeAssetId(),
                    amount: 10.0)
  })

This will create and sign the transaction that originated from the sourceAccountKeyPair. Every 30 seconds this function will re-construct this transaction with a new fee (increased by 100 stroops), repeating signing and submitting. Once the transaction is successful, the function will return the transaction body. Note, that any other error will terminate the retry cycle and an exception will be thrown.

Accessing Horizon SDK

It’s very simple to use the Horizon SDK connecting to the same Horizon instance as a Wallet class. To do so, simply call:

Kotlin
TypeScript
Flutter
Swift

val server = wallet.stellar().server

const server = wallet.stellar().server;

var server = wallet.stellar().server;

let server = wallet.stellar.server

And you can work with Horizon Server instance:

Kotlin
TypeScript
Flutter
Swift

val stellarTransaction = server.transactions().transaction("transaction_id")

const stellarTransaction = server
  .transactions()
  .forAccount("account_id")
  .call();

var transactions = await server.transactions.forAccount("accountId").execute();

let transactionsEnum = await server.transactions.getTransactions(forAccount: "accountId")
switch transactionsEnum {
case .success(let page):
    let transactions = page.records
case .failure(let error):
    throw error
}

​Accounts

​Build Transaction

​Building Basic Transactions

​Create Account

​Modify Account

​Modify Assets (Trustlines)

​Swap

​Path Pay

​Set Memo

​Account Merge

​Fund Testnet Account

​Building Advanced Transactions

​Adding an Operation

​Sponsoring Transactions

​Sponsor Operations

​Sponsoring Account Creation

​Sponsoring Account Creation and Modification

​Fee-Bump Transaction

​Using XDR to Send Transaction Data

​Submit Transaction

​Accessing Horizon SDK

Accounts

Build Transaction

Building Basic Transactions

Create Account

Modify Account

Modify Assets (Trustlines)

Swap

Path Pay

Set Memo

Account Merge

Fund Testnet Account

Building Advanced Transactions

Adding an Operation

Sponsoring Transactions

Sponsor Operations

Sponsoring Account Creation

Sponsoring Account Creation and Modification

Fee-Bump Transaction

Using XDR to Send Transaction Data

Submit Transaction

Accessing Horizon SDK