Skip to main content

Stellar Network

info

This guide is available on three different programming languages: Typescript, Kotlin and Flutter (Dart). 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:

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

Now we can create a keypair:

let accountKeyPair = account.createKeypair();
info

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).

const txBuilder = await stellar.transaction({
  sourceAddress: sourceAccountKeyPair,
});
const tx = txBuilder.createAccount(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.

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

const tx = 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.

const newSignerKeyPair = account.createKeypair();

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

Remove a signer from the account.

const tx = txBuilder.removeAccountSigner(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.

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

Modify Assets (Trustlines)​

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

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

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

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

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

Swap​

Exchange an account's asset for a different asset. The account must have a trustline for the destination asset.

const txBuilder = await stellar.transaction({
  sourceAddress: sourceKp,
});
const usdcAsset = new IssuedAssetId(
  "USDC",
  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
);
const txn = txBuilder.swap(new NativeAssetId(), usdcAsset, ".1").build();

Path Pay​

Send one asset from the source account and receive a different asset in the destination account.

const txBuilder = await stellar.transaction({
  sourceAddress: sourceKp,
});
const usdcAsset = new IssuedAssetId(
  "USDC",
  "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
);
const txn = txBuilder
  .pathPay({
    destinationAddress: receivingKp.publicKey,
    sendAsset: new NativeAssetId(),
    destAsset: usdcAsset,
    sendAmount: "5",
  })
  .build();

Set Memo​

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

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

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

Account Merge​

Merges account into a destination account.

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

Fund Testnet Account​

Fund an account on the Stellar test network

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

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.

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

First, the account must be created.

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

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

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);
note

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

Signed transaction can be submitted by the wallet.

await wallet.stellar().submitTransaction(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:

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);

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".

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,
  }),
);

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 create a building function (describing which operations are to be sponsored) and pass it to the sponsoring method:

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);
info

Only some operations can be sponsored, and a sponsoring builder 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:

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);

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 method. 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 sponsoring method (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).

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);

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 method 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.

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();

Second, sign transaction with both keys.

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

Next, create a fee bump, targeting the transaction.

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

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.

await wallet.stellar().submitTransaction(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:

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

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

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();

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

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

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

return signedTransaction.toXDR();

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

const signedTransaction = stellar.decodeTransaction(xdrString);

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

Submit Transaction​

info

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.

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

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:

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

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

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:

const server = wallet.stellar().server;

And you can work with Horizon Server instance:

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