From c2c92e2f48a9e3640932531bb1cb064e3cec0088 Mon Sep 17 00:00:00 2001 From: Bri Wylde <92327786+briwylde08@users.noreply.github.com> Date: Tue, 21 Oct 2025 14:19:26 -0600 Subject: [PATCH] Add wallet playbook to docs --- config/theme/navbar.ts | 7 +- docs/build/apps/README.mdx | 4 +- docs/build/apps/overview.mdx | 2 + docs/build/wallet-playbook/README.mdx | 14 + .../wallet-playbook/infrastructure/README.mdx | 13 + .../infrastructure/onchain-data.mdx | 46 +++ docs/build/wallet-playbook/introduction.mdx | 20 ++ .../wallet-playbook/key-management/README.mdx | 13 + .../key-management-providers.mdx | 15 + .../passkeys-and-smart-wallets.mdx | 18 ++ .../public-private-keys-overview.mdx | 29 ++ docs/build/wallet-playbook/wallets/README.mdx | 13 + .../wallets/custody-models.mdx | 73 +++++ .../wallets/sponsorship/README.mdx | 13 + .../wallets/sponsorship/estimate.mdx | 17 ++ .../wallets/sponsorship/sponsor-classic.mdx | 277 ++++++++++++++++++ .../wallets/sponsorship/sponsor-smart.mdx | 50 ++++ .../wallets/sponsorship/why-sponsor.mdx | 32 ++ .../wallet-playbook/wallets/wallet-types.mdx | 94 ++++++ routes.txt | 16 + 20 files changed, 763 insertions(+), 3 deletions(-) create mode 100644 docs/build/wallet-playbook/README.mdx create mode 100644 docs/build/wallet-playbook/infrastructure/README.mdx create mode 100644 docs/build/wallet-playbook/infrastructure/onchain-data.mdx create mode 100644 docs/build/wallet-playbook/introduction.mdx create mode 100644 docs/build/wallet-playbook/key-management/README.mdx create mode 100644 docs/build/wallet-playbook/key-management/key-management-providers.mdx create mode 100644 docs/build/wallet-playbook/key-management/passkeys-and-smart-wallets.mdx create mode 100644 docs/build/wallet-playbook/key-management/public-private-keys-overview.mdx create mode 100644 docs/build/wallet-playbook/wallets/README.mdx create mode 100644 docs/build/wallet-playbook/wallets/custody-models.mdx create mode 100644 docs/build/wallet-playbook/wallets/sponsorship/README.mdx create mode 100644 docs/build/wallet-playbook/wallets/sponsorship/estimate.mdx create mode 100644 docs/build/wallet-playbook/wallets/sponsorship/sponsor-classic.mdx create mode 100644 docs/build/wallet-playbook/wallets/sponsorship/sponsor-smart.mdx create mode 100644 docs/build/wallet-playbook/wallets/sponsorship/why-sponsor.mdx create mode 100644 docs/build/wallet-playbook/wallets/wallet-types.mdx diff --git a/config/theme/navbar.ts b/config/theme/navbar.ts index 6741f0a7e..e722b9abc 100644 --- a/config/theme/navbar.ts +++ b/config/theme/navbar.ts @@ -35,7 +35,12 @@ const build: NavbarItem = { }, { type: 'html', - value: '
Build Applications', + value: '
Stellar Wallet Playbook', + className: 'subtitle', + }, + { + type: 'html', + value: '
Application Tutorials', className: 'subtitle', }, { diff --git a/docs/build/apps/README.mdx b/docs/build/apps/README.mdx index 3029e18b1..654f1c8cd 100644 --- a/docs/build/apps/README.mdx +++ b/docs/build/apps/README.mdx @@ -1,6 +1,6 @@ --- title: "Build Blockchain Apps: Guides, Tools, and Best Practices for Development" -sidebar_label: Build Applications +sidebar_label: Application Tutorials description: "Learn how to build blockchain apps with guides, tools, and best practices. Explore key concepts, integration tips, and resources for development on Stellar." sidebar_position: 30 --- @@ -9,6 +9,6 @@ sidebar_position: 30 import DocCardList from "@theme/DocCardList"; -This section walks you through design considerations for applications and tutorials for building applications with or without smart contracts. +This section contains various tutorials for building applications with or without smart contracts on Stellar. diff --git a/docs/build/apps/overview.mdx b/docs/build/apps/overview.mdx index 647f47cc4..d4c392ced 100644 --- a/docs/build/apps/overview.mdx +++ b/docs/build/apps/overview.mdx @@ -5,6 +5,8 @@ sidebar_label: Introduction description: "Build a wallet application on Stellar with the Wallet SDK using Typescript, Flutter, Kotlin or Swift. Explore key features, setup steps, and best practices." --- +**this page will be deleted** + # Overview Stellar is an open-source distributed ledger that you can use as a backend to power various applications and services, such as wallets, payment apps, currency exchanges, micropayment services, platforms for in-game purchases, and more — check out projects being built on Stellar: [Stellar Ecosystem Projects](https://stellar.org/ecosystem/projects#Projects). diff --git a/docs/build/wallet-playbook/README.mdx b/docs/build/wallet-playbook/README.mdx new file mode 100644 index 000000000..26bb15512 --- /dev/null +++ b/docs/build/wallet-playbook/README.mdx @@ -0,0 +1,14 @@ +--- +title: Stellar Wallet Playbook +sidebar_label: Stellar Wallet Playbook +description: "Learn how to build wallets with guides, tools, and best practices. Explore key concepts, integration tips, and resources for development on Stellar." +sidebar_position: 20 +--- + +# Stellar Wallet Playbook + +import DocCardList from "@theme/DocCardList"; + +All you need to know about building a wallet on Stellar. + + diff --git a/docs/build/wallet-playbook/infrastructure/README.mdx b/docs/build/wallet-playbook/infrastructure/README.mdx new file mode 100644 index 000000000..5fd7e52d5 --- /dev/null +++ b/docs/build/wallet-playbook/infrastructure/README.mdx @@ -0,0 +1,13 @@ +--- +title: Infrastructure +sidebar_label: Infrastructure +sidebar_position: 20 +--- + +# Infrastructure + +import DocCardList from "@theme/DocCardList"; + +Infrastructure. + + diff --git a/docs/build/wallet-playbook/infrastructure/onchain-data.mdx b/docs/build/wallet-playbook/infrastructure/onchain-data.mdx new file mode 100644 index 000000000..93124bf7f --- /dev/null +++ b/docs/build/wallet-playbook/infrastructure/onchain-data.mdx @@ -0,0 +1,46 @@ +--- +sidebar_label: "Onchain Data" +sidebar_position: 1 +--- + +# Onchain Data + +Building a Stellar wallet means more than just sending and receiving payments, you must know what data is needed, how to get it, and how to keep it in sync. This guide explains the types of data Stellar wallets may require, how to access it, and best practices for working with it. + +## Core Wallet Data + +As wallets implement their internal functionality, they may need to access data stored on and off-chain. A few examples of data a wallet may need to access are: + +- **Account state**: Token balances, signers, thresholds, and subentries. + +- **Token information**: Trustlines, asset codes, icon. + +- **Transaction history**: Payments, trades, offers, and smart contract calls. + +- **Contract state**: If using smart contracts. + +## How to Access Wallet Data + +The Stellar network is open and public, meaning anyone can access the data stored on the network. However, accessing this data can be complex and time-consuming. To make this easier, there are a few tools available to help you get the data you need. + +### RPC + +Stellar RPC is an interface that provides direct access to the Stellar network's ledger state and smart contract functionality. Unlike Horizon's REST API, which focuses on indexed, human-readable history and account data, Stellar RPC is designed for developers who need to interact with the network at the protocol level, especially for building on Soroban, Stellar's smart contracts platform. Through RPC, you can read raw ledger entries, query and stream recent contract events, simulate transactions before submission, and retrieve contract code or state. It is the preferred interface for dApps, indexers, and infrastructure services that require precise, real-time access to on-chain data beyond what Horizon exposes. + +📖 Learn more about RPC in the [RPC documentation](https://developers.stellar.org/docs/data/apis/rpc). + +## Indexers + +Indexers on Stellar are specialized services that collect, process, and organize raw blockchain data, often going beyond what Horizon or RPC provide out of the box. While Horizon indexes core network data like accounts, transactions, payments, and contract events, external indexers can ingest the entire ledger stream to create highly customized, query-optimized datasets. Popular indexer architectures often involve a streaming ingestion layer, a transformation pipeline, and a queryable database, allowing developers and businesses to access deep, application-specific insights from the Stellar network. + +📖 Check out the available indexers in the [Indexers documentation](https://developers.stellar.org/docs/data/indexers/indexer-providers). + +### Horizon + +Horizon provides a REST API for the Stellar network. It can be used to get account data, transaction history, and more. It has been broadly used by the Stellar ecosystem for years to fetch on-chain data for Classic wallets. With the introduction of Smart Contracts on Stellar, new projects usually adopt RPCs combined with indexers since they provide a more complete solution to interact with smart contracts and fetch the data they need. + +📖 Learn more about Horizon in the [Horizon documentation](https://developers.stellar.org/docs/data/apis/horizon). + +:::warning[Important] On August 1, 2024, the publicly accessible SDF-hosted Horizon had its historical data truncated to one year. That update optimized the performance of the publicly accessible Horizon and ensured a streamlined experience for all users. Consider third-party ecosystem providers of Horizon. + +[Check out Horizon Providers for a list of third-party providers.](https://developers.stellar.org/docs/data/apis/api-providers) ::: diff --git a/docs/build/wallet-playbook/introduction.mdx b/docs/build/wallet-playbook/introduction.mdx new file mode 100644 index 000000000..092789467 --- /dev/null +++ b/docs/build/wallet-playbook/introduction.mdx @@ -0,0 +1,20 @@ +--- +sidebar_label: "Introduction" +sidebar_position: 1 +--- + +# Introduction + +As user demand for powerful, accessible financial services continues to rise, **wallet builders** have a unique opportunity to define the next generation of digital finance. **The Stellar network** is uniquely positioned to support you on this journey — not just with powerful infrastructure, but with a decade-long track record of enabling real-world utility at scale. + +With the largest network of **on/off-ramps**, a growing portfolio of **Real World Assets (RWAs)** and **yield-bearing products**, and native **DeFi** protocols, Stellar offers the tools you need to bridge **onchain and offchain** finance – enabling users to **earn, save, spend, and transact** seamlessly across borders. + +This playbook is designed to help you navigate key design choices — from choosing between **Classic and Smart Wallets** to deciding the right integrations you need. Whether you’re just starting out or scaling to millions of users, this guide will help you build a wallet that’s **secure, user-friendly**, and ready for the next wave of growth. + +:::note + +This playbook is a work in progress. We're actively working to add more content and improve the quality of the documentation. + +Your feedback is welcome! Please [open an issue](https://github.com/brunomuler/wallets-playbook/issues), [submit a pull request](https://github.com/brunomuler/wallets-playbook/pulls) or send a feedback directly [here](https://airtable.com/appEVqkGfPR0H6XLF/pagGiCQ5jrswCq04Y/form). + +::: diff --git a/docs/build/wallet-playbook/key-management/README.mdx b/docs/build/wallet-playbook/key-management/README.mdx new file mode 100644 index 000000000..e2dca4d41 --- /dev/null +++ b/docs/build/wallet-playbook/key-management/README.mdx @@ -0,0 +1,13 @@ +--- +title: Key Management +sidebar_label: Key Management +sidebar_position: 30 +--- + +# Key Management + +import DocCardList from "@theme/DocCardList"; + +Key Management. + + diff --git a/docs/build/wallet-playbook/key-management/key-management-providers.mdx b/docs/build/wallet-playbook/key-management/key-management-providers.mdx new file mode 100644 index 000000000..d6863894d --- /dev/null +++ b/docs/build/wallet-playbook/key-management/key-management-providers.mdx @@ -0,0 +1,15 @@ +--- +sidebar_label: "Key Management Providers" +sidebar_position: 3 +hide_table_of_contents: true +--- + +**directory placeholder** + +# Key Management Providers + +Modern key management solutions provide enhanced security and user experience by leveraging external key managers, hardware security modules, and advanced authentication methods like passkeys. + +These solutions help wallet developers implement secure key storage and management without requiring users to directly handle private keys, while maintaining the security benefits of non-custodial wallets. + +## Key Management Solutions diff --git a/docs/build/wallet-playbook/key-management/passkeys-and-smart-wallets.mdx b/docs/build/wallet-playbook/key-management/passkeys-and-smart-wallets.mdx new file mode 100644 index 000000000..29eff9790 --- /dev/null +++ b/docs/build/wallet-playbook/key-management/passkeys-and-smart-wallets.mdx @@ -0,0 +1,18 @@ +--- +sidebar_label: "Passkeys" +sidebar_position: 3 +--- + +# Passkeys + +Passkeys are a passwordless authentication standard that uses cryptography to provide a more convenient way to sign in to websites and apps. + +With passkeys, users can authenticate using their biometric data, PIN or pattern, removing the need of memorizing and typing passwords. In crypto, passkeys also remove the need of storing private keys or writing down the mnemonic phrase, a common friction point and security risk. + +# Passkeys on Stellar + +With the introduction of [Protocol 21](https://stellar.org/blog/developers/announcing-protocol-21), which introduced [native support for secp256r1 verification](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0051.md) in smart contracts, passkeys became a viable option for key management. Users can now use passkeys to sign transactions, without the hassle of managing private keys. + +📖 Learn more about Passkeys on Stellar in the article [Passkeys, a Light Introduction to Improving Blockchain’s UX](https://stellar.org/blog/developers/passkeys-a-light-introduction-to-improving-blockchain-s-ux) + +📖 [Learn more about Smart Wallets and check out examples of how to use passkeys](https://developers.stellar.org/docs/build/apps/smart-wallets) diff --git a/docs/build/wallet-playbook/key-management/public-private-keys-overview.mdx b/docs/build/wallet-playbook/key-management/public-private-keys-overview.mdx new file mode 100644 index 000000000..99e8a8342 --- /dev/null +++ b/docs/build/wallet-playbook/key-management/public-private-keys-overview.mdx @@ -0,0 +1,29 @@ +--- +sidebar_label: "Public/Private Key Overview" +sidebar_position: 1 +--- + +# Public/Private Keys Overview + +This page explains the basics of public/private key cryptography and how it works on Stellar, if you are already familiar with the concept, you can skip to the the next section. + +Public/private key cryptography is the foundation of account security not only on Stellar, but across nearly all blockchains. The principle is the same everywhere: + +- A **public key** identifies you on the network. +- A **private key** proves you are the rightful owner and authorizes actions. + +The public key (Account ID) is mathematically derived from the private key, ensuring that anyone can verify your identity without ever knowing your secret. + +### Public Key (Account ID) + +- **Format**: Begins with **G...** for Classic Wallets and **C...** for Smart Wallets. +- **Purpose**: Public identifier for receiving payments and being recognized on the network. +- **Usage**: Safe to share — similar to a bank account number, but without revealing your ability to move funds. +- **Derivation**: Generated from the private key using Ed25519 elliptic-curve cryptography. + +### Private Key (Secret Key) + +- **Format**: Begins with **S...** +- **Purpose**: Signs transactions to authorize any change to the account or accounts it has signing power over — sending funds, creating trustlines, altering signers, etc. +- **Security Principle**: Whoever has the private key controls the account. +- **Relationship**: The public key is mathematically derived from it, but the reverse is computationally impossible. diff --git a/docs/build/wallet-playbook/wallets/README.mdx b/docs/build/wallet-playbook/wallets/README.mdx new file mode 100644 index 000000000..232bbb4ea --- /dev/null +++ b/docs/build/wallet-playbook/wallets/README.mdx @@ -0,0 +1,13 @@ +--- +title: Wallets +sidebar_label: Wallets +sidebar_position: 10 +--- + +# Wallets + +import DocCardList from "@theme/DocCardList"; + +Wallets. + + diff --git a/docs/build/wallet-playbook/wallets/custody-models.mdx b/docs/build/wallet-playbook/wallets/custody-models.mdx new file mode 100644 index 000000000..03d42c720 --- /dev/null +++ b/docs/build/wallet-playbook/wallets/custody-models.mdx @@ -0,0 +1,73 @@ +--- +title: Custody Models +sidebar_label: "Custody Models" +sidebar_position: 2 +description: Understand the difference between custodial and non-custodial wallets on Stellar, and how this choice impacts architecture, compliance, and user experience. +--- + +# Custody Models + +When building on the blockchain, one of the first architectural decisions you'll face is whether to create a **custodial** or **non-custodial** wallet. This decision affects how user accounts are managed, who holds the keys, how transactions are authorized, and the level of trust required from users. + +## Custodial Wallets + +In a **custodial wallet**, the application or service **controls the user's private keys** and manages accounts on their behalf. This means the service can initiate transactions, manage assets, and even recover accounts for users. Services will many times use omnibus accounts to manage user accounts, using an internal identification to identify the user. + +### Characteristics + +- User accounts are often held in a central ledger (database or omnibus account model). +- The backend signs transactions on behalf of users. +- User identity is typically tied to the service's authentication system. +- Suitable for services that want full control over user experience (e.g., exchanges). + +### Advantages + +- Simplified UX since the user doesn't need to manage keys or sign every transaction. +- Easier account recovery and support. +- Greater ability to enforce compliance or transaction logic. + +### Tradeoffs + +- Higher security and compliance responsibilities. +- Central point of failure. +- Regulatory obligations in many jurisdictions (KYC, custody licenses, etc.). + +## Non-Custodial Wallets + +A **non-custodial wallet** allows the user to **own and control their private keys**. The wallet software facilitates key generation, signing, and submission of transactions, but never has access to the keys themselves. + +### Characteristics + +- Accounts are controlled by end users, the applications will not have access to the private keys. +- The wallet app acts as an interface only. +- Can use different recovery mechanisms as described in the [Key Management](../key-management) section. + +### Advantages + +- No need to trust a third party to secure funds. +- User retains full control over assets and transaction authorization. +- Lower regulatory burden for the app provider in many jurisdictions. + +### Tradeoffs + +- Harder to support account recovery or fraud protection. +- User education and key management UX become critical. +- More difficult to abstract XLM requirements (possible using [sponsorship](./sponsorship). + +## Hybrid & Delegated Models + +Some wallets use a **hybrid model**, where users control the keys but delegate signing rights to a secure enclave or a managed key provider (e.g., [Privy](https://docs.privy.io/), [Turnkey](https://www.turnkey.com/), [DFNS](https://dfns.co/)). + +These setups: + +- Retain non-custodial benefits while improving UX. +- Often integrate with social login or passkeys. +- Can be used to support both Classic and Smart Wallets. + +Learn more about delegated signing and SEP-30 recovery: [Signatures & Multisig](https://developers.stellar.org/docs/learn/fundamentals/transactions/signatures-multisig) [SEP-30: Account Recovery](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md) + +:::note + +This documentation mainly assumes the reader is building a non-custodial wallet. + +::: diff --git a/docs/build/wallet-playbook/wallets/sponsorship/README.mdx b/docs/build/wallet-playbook/wallets/sponsorship/README.mdx new file mode 100644 index 000000000..e565b2ab6 --- /dev/null +++ b/docs/build/wallet-playbook/wallets/sponsorship/README.mdx @@ -0,0 +1,13 @@ +--- +title: Sponsorship +sidebar_label: Sponsorship +sidebar_position: 10 +--- + +# Wallets + +import DocCardList from "@theme/DocCardList"; + +Sponsorship. + + diff --git a/docs/build/wallet-playbook/wallets/sponsorship/estimate.mdx b/docs/build/wallet-playbook/wallets/sponsorship/estimate.mdx new file mode 100644 index 000000000..4b8e79725 --- /dev/null +++ b/docs/build/wallet-playbook/wallets/sponsorship/estimate.mdx @@ -0,0 +1,17 @@ +--- +sidebar_label: "Estimate costs" +sidebar_position: 4 +hide_table_of_contents: true +--- + +**sponshorship calculator placeholder** + +# Estimate Sponsorship Costs + +Use the calculator below to estimate the costs of sponsoring **Classic Wallets** on the Stellar Network. + +:::warning + +This calculator provides an estimate for sponsoring **Classic Wallets** on the Stellar Network. These figures are for guidance only; actual costs may vary and are not guaranteed. + +::: diff --git a/docs/build/wallet-playbook/wallets/sponsorship/sponsor-classic.mdx b/docs/build/wallet-playbook/wallets/sponsorship/sponsor-classic.mdx new file mode 100644 index 000000000..0f8745925 --- /dev/null +++ b/docs/build/wallet-playbook/wallets/sponsorship/sponsor-classic.mdx @@ -0,0 +1,277 @@ +--- +sidebar_label: "Sponsor classic wallets" +sidebar_position: 2 +--- + +# Sponsor Classic Wallets + +This section assumes the reader has a basic understanding of [Lumens](https://developers.stellar.org/docs/learn/fundamentals/lumens) (XLM), the native token of the Stellar Network. Sponsorship is mainly focused only applications offering non-custodial wallets. + +## Classic Wallets + +Before looking into sponsorship, it's important to first understand reserves and fees on the Stellar network for Classic Wallets and why they exist. + +[Skip ahead if you're already familiar with this section.](#how-sponsorship-works) + +### Base Reserves + +The base reserve is an amount of Lumens (currently set to 0.5 XLM), used as a multiplier to calculate the minimum balance. The minimum balance is the amount of XLM necessary to create a wallet or to change a wallet options that require saving data to the network. Think about it as a way to pay for storing data on the network and to avoid spam. + +Even if an application's features only use assets other than XLM, having a minimum balance of XLM is still required to operate it. [Learn more about base reserves](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#base-reserves-and-subentries). + +:::note The most common base reserves used by accounts are: + +- Account creation: 2 base reserves (1 XLM) - [learn more about account creation](https://developers.stellar.org/docs/build/guides/basics/create-account) +- Adding trustlines to accept assets (1x base reserve = 0.5 XLM per asset trustline) + +[Check a full list of account subentries](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries). ::: + +Base reserves are temporarily locked on the account. If the data is removed or if the account is deleted (merged into another account), the minimum balance will be unlocked and available for use. More about recovering the reserves is covered later on. + +#### Example: Funding base reserves **without sponsorship** + +Given an account "A" with a balance of 5 XLM willing to fund a Stellar address "B" (not funded). + +To fund it, account "A" sends 1XLM to address B (the used operation is Create Account, not Payment). + +After completing the transaction, account B is now funded with 1 XLM. Given the requirement of two base reserves, this account has 0 XLM available to use, so it can't add any additional reserves or submit transactions (pay for fees) in its current state. + +Without sponsorship, the lumens were actually transferred from account A to account B, so account B has control over them. + +**diagram placeholder** **diagram placeholder** + +> **Note**: This section covers reserves for Classic wallets. Smart wallets work in a different way. To learn more about Smart wallets, see [Sponsor Smart Wallets](./sponsor-smart). + +### [Fees](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering) + +When a Stellar account submits a transaction to the network, it will need to pay a fee to be processed. This is also called "gas" in some networks. This fee in the Stellar Network, although small, helps avoid spam on the network and can be used to prioritize transactions, especially if there's a network [surge](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering#surge-and-dynamic-pricing). The minimum fee on the Network is set to 100 stroops (stoop is the minimum fraction of lumens: 0.0000001 XLM) or 0.00001 XLM. + +Applications built on Stellar can define the maximum fee amount they are willing to pay on each transaction to ensure that the submitted transactions will be processed by the network ([learn more about fee strategies](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering#inclusion-fee-pricing-strategies)). The set value is used as a limit, the effective fee paid will depend on the network state at the time of submission. If there's no surge, the fee paid will still be the minimum even though the maximum fee amount was higher. + +By default, the fee cost in XLM is deducted from the account submitting the transaction; not having enough Lumens in that account will result in a submission failure. Fee sponsoring ([Fee-Bump Transactions](https://developers.stellar.org/docs/encyclopedia/fee-bump-transactions)) can change this, allowing an wallet developer to pay for fees on behalf of the user, so they don't need to keep an XLM balance in their accounts. + +As an example, without using fee sponsoring, sending 1 XLM from an account A to account B deducts 1.00001 XLM from account A since it pays for the minimum fee of 0.00001 XLM + 1XLM sent. + +## How sponsorship works {#how-sponsorship-works} + +:::note This guide covers both base reserve and fee sponsorship (fee bump). These are independent features - you can implement either one or both, depending on your application's needs. ::: + +### [Sponsoring base reserves](https://developers.stellar.org/docs/build/guides/transactions/sponsored-reserves) + +When sponsoring base reserves, the application will elect to lock Lumens on behalf of the users, so users don't need to hold any lumens. To do this, the application will format a transaction that includes an operation that defines that all the following operations in that same transaction that require reserves will be sponsored by its own account. Then, after defining all the necessary operations, it needs to define another operation that closes the sponsorship. This allows the application to say which operations it wants to sponsor explicitly, and the need to stop sponsoring in the same transaction guarantees that no additional sponsor reserves can be created without the sponsor's consent. If the user decides to change their own account in ways that require additional reserves, these won't be locked on the sponsor's account. + +An account sponsorship uses a transaction sandwich of three or more operations in a single transaction: + +1. **Begin Sponsoring Future Reserves**: Initiates the sponsorship. This operation (source = sponsor) designates a sponsored account ID whose future reserve increases will be paid by the sponsor. + +2. **Include operations that require reserves**: Include operations that require reserves, like creating the account, a trustline, etc. + +3. **End Sponsoring Future Reserves**: Ends the sponsorship initiation segment. This operation (source = the new account) lets the new account accept the sponsorship. It must be run by (or on behalf of) the sponsored account and is only valid inside the same transaction after a matching Begin Sponsoring operation. + +This transaction that starts with the intent of sponsoring, includes operations and ends with closing sponsorship is called a sandwich transaction, and it may look like this: + +**diagram placeholder** + +After building the sponsoring transaction, it will need the signature of both the sponsor's and the account being sponsored (or any account with enough signing power to do so) before being submitted to the network. This is a requirement so that both parties approve what's being submitted. + +**diagram placeholder** + +An account that sponsors two external accounts may look like this: + +**diagram placeholder** + +Note that the users' accounts don't need to hold any Lumens and that all the reserves were added to the sponsor account. Lumens never left the sponsor account. The sponsor account in the example has 5 locked lumens from: + +- Its own account creation (2x base reserve = 1 XLM) +- Creating 2 additional accounts (4x base reserve = 2 XLM) +- Sponsoring 2 trustlines for two accounts (4x base reserve = 2 XLM) + +📖 Learn more about [transactions and operations](https://developers.stellar.org/docs/learn/fundamentals/transactions) in the Stellar documentation. + +[Check the sponsored reserves documentation](https://developers.stellar.org/docs/encyclopedia/sponsored-reserves) + +### Code example: Sponsoring account creation + +```js +import { + Server, + Keypair, + TransactionBuilder, + Networks, + BASE_FEE, + Operation, +} from "stellar-sdk"; + +const server = new Server("https://horizon-testnet.stellar.org"); + +async function createSponsoredAccount() { + const sponsor = Keypair.fromSecret(""); // wallet's funding account + const newUser = Keypair.random(); // user controls this key + const sponsorAccount = await server.loadAccount(sponsor.publicKey()); + + // Sandwich pattern: begin sponsorship, create account, end sponsorship + const tx = new TransactionBuilder(sponsorAccount, { fee: BASE_FEE }) + .addOperation( + Operation.beginSponsoringFutureReserves({ + sponsoredId: newUser.publicKey(), // designate the account being sponsored + }), + ) + .addOperation( + Operation.createAccount({ + destination: newUser.publicKey(), // user's account + startingBalance: "0", // no XLM needed from user + }), + ) + .addOperation( + Operation.endSponsoringFutureReserves({ + source: newUser.publicKey(), + }), + ) + .setNetworkPassphrase(Networks.TESTNET) + .setTimeout(180) + .build(); + + // Both sponsor and user sign + tx.sign(sponsor); + tx.sign(newUser); + + await server.submitTransaction(tx); +} +``` + +In the code above, notice how the only additions compared to a normal `CreateAccount` flow are the two sponsoring operations wrapping around the `CreateAccount` op. The `startingBalance` is set to "0" because the **base reserve (1 XLM)** for the new account will be taken from the sponsor's account instead of requiring the new account to hold it. After submission, the new account exists on the network without the user or sponsor sending it lumens directly – the reserve is sponsored. + +The sponsoring account's XLM reserve **increases by 1 XLM** (locked for this sponsorship), while the new account's minimum balance requirement is satisfied off-chain by the sponsor. As a best practice, the sponsor can later revoke the sponsorship (using a `RevokeSponsorship` operation) to reclaim that 1 XLM, but only if the new account has acquired enough XLM to cover its own reserves or is going to be deleted. + +### Code example: Sponsoring Trustlines + +```js +import { + Server, + Keypair, + TransactionBuilder, + Networks, + BASE_FEE, + Operation, + Asset, +} from "stellar-sdk"; + +const server = new Server("https://horizon-testnet.stellar.org"); + +async function addSponsoredTrustline() { + const sponsor = Keypair.fromSecret(""); // wallet funding account + const user = Keypair.fromSecret(""); // user account + const asset = new Asset("MYTOKEN", sponsor.publicKey()); + const sponsorAccount = await server.loadAccount(sponsor.publicKey()); + + // Sandwich: begin sponsorship, change trust, end sponsorship + const tx = new TransactionBuilder(sponsorAccount, { fee: BASE_FEE }) + .addOperation( + Operation.beginSponsoringFutureReserves({ + sponsoredId: user.publicKey(), // sponsor reserves for this user + }), + ) + .addOperation( + Operation.changeTrust({ + source: user.publicKey(), + asset, + limit: "1000", // optional limit + }), // user creates the trustline + ) + .addOperation( + Operation.endSponsoringFutureReserves({ + source: user.publicKey(), // user accepts sponsorship + }), + ) + .setNetworkPassphrase(Networks.TESTNET) + .setTimeout(120) + .build(); + + // Signatures from both sponsor and user + tx.sign(sponsor); + tx.sign(user); + + await server.submitTransaction(tx); +} +``` + +In this sponsored trustline transaction, the `ChangeTrust` operation is sandwiched between `BeginSponsoringFutureReserves` and `EndSponsoringFutureReserves`. The sponsor's account (S1) is the source for the first operation, and the user's account (A) is the source for both the trustline creation and the end-sponsoring operation. After execution, the asset trustline is established for the user, and the **0.5 XLM reserve** for that trustline is taken from the sponsor's account balance instead of the user's. Just like with account creation, the user retains full control over their account and the new trustline, while the sponsor merely locks up some of their XLM to cover the reserve. + +**Behind the scenes**: The Stellar ledger records that the trustline entry is sponsored by the sponsor’s account (it will show a sponsor attribute in Horizon data). The sponsor's minimum balance **increases to cover the extra 0.5 XLM reserve** on behalf of the user, and the user's minimum balance does not increase for this trustline. In the future, if the user obtains sufficient lumens, the sponsorship can be reversed (using a `RevokeSponsorship` op) so the user takes over the reserve or the trustline can be removed to release the reserve. + +### Cancelling or removing sponsorship + +To remove sponsorship, the account being sponsored must perform operations that release reserves (e.g., removing trustlines or merging accounts). The sponsor can explicitly revoke sponsorship in a transaction approved by both parties. + +### Sponsoring base reserves FAQ + +**Once sponsoring begins, should future operations be reserved by the sponsor?** +No, sponsorship only covers explicitly defined operations within the sandwich transaction. + +**Who holds the sponsorship funds?** +Lumens remain locked within the sponsor's account and are never transferred to sponsored accounts. + +**Can sponsorship be removed from active accounts?** +Yes, but only after sponsored accounts clear sponsored reserves or through mutual consent to end sponsorship. + +### Sponsoring transaction fees (gas) + +Transaction fees sponsorship uses "fee bump transactions," allowing sponsors to pay transaction fees on behalf of user accounts. Fee bumps wrap user transactions in a higher-fee transaction paid by the sponsor. + +[Check the fee bump transactions documentation](https://developers.stellar.org/docs/encyclopedia/fee-bump-transactions). + +## Comparison: With vs. Without Sponsorship + +To summarize the differences between traditional flows and sponsored flows in a wallet context: + +| Aspect | Without Sponsorship | With Sponsorship | +| --- | --- | --- | +| **Lumens Requirement** | Users (or their wallet provider) must provide XLM for new accounts and trustlines upfront | A designated sponsor account provides the lumens for reserves, allowing users to start with zero XLM of their own | +| **Transaction Structure** | Standard operations (CreateAccount, ChangeTrust, etc.) | Adds only two extra operations (begin and end sponsorship) around the normal operation. The logic remains the same - essentially a small "wrapper" around existing operations | +| **Signatures and Control** | Only the account performing the operation needs to sign | Sponsored transactions require an extra signature (the sponsored account's) to approve the arrangement. The sponsoring account never gains control over the user's account; it only locks some of its XLM as a guarantee | +| **Onboarding UX** | Users must acquire XLM before they can create accounts or add trustlines, creating friction for new users | Users can receive their first assets directly as another asset issued on Stellar and transact in those assets, while the wallet application invisibly handles the lumens overhead. This dramatically lowers friction for new users | +| **Recovery of Funds** | If a wallet sends lumens to a user, it has no guarantee of retrieving them | The sponsor can remove sponsorship when the user later deposits lumens or no longer needs it. Reserved lumens (1 XLM for an account, 0.5 XLM per trustline, etc.) unlock in the sponsor's available balance once the user covers their own reserves or sponsored entries are removed | + +## Calculating sponsorship costs + +There are costs related to sponsoring the user's base reserves or transaction fees. The cost is calculated in Lumens, so the price in any currency, such as USD, will vary. This section will suggest a simple model that you can use to calculate these costs. + +:::tip[Estimate costs] [Estimate the average cost of sponsoring for Classic Wallets](./estimate) ::: + +## Creating a sponsorship infrastructure + +The [stellar/wallet-backend](https://github.com/stellar/wallet-backend) project provides server-side tooling to make creating and using wallets seamless. + +### Key Features + +- **Sponsored Account Creation** + Supports creating accounts and paying reserves on behalf of new users. +- **Fee Sponsorship ("Gasless" UX)** + Uses **fee-bump transactions** so a distribution account pays transaction fees. +- **Channel Accounts** + Manages sequence numbers and scales throughput by using pre-funded channel accounts. +- **Secure API** + Exposes endpoints for building, signing, and submitting transactions, secured by JWT-based authentication. + +### Typical Flow + +1. **Frontend** + - User signs an operation according to their wallet’s logic + - App sends the signed payload to the backend. + +2. **Backend (wallet-backend)** + - Builds the transaction using a **channel account** for sequence numbers. + - Wraps it in a **fee-bump transaction** so the **distribution account** pays the fee (and any reserve if needed). + - Submits the transaction to Stellar RPC. + - Polls for confirmation and returns the result. + +3. **Result** + - User’s wallet action succeeds. + - User never needed to hold XLM for fees or reserves. + - Sponsor absorbs costs and can manage them. + +### Adding funds to the sponsorship account + +To fund accounts, you can acquire XLM from a variety of sources including exchanges. + +:::info[Exchanges] [Check a list of exchanges](https://stellar.org/developers/guides/on-ramps/exchanges-list) ::: diff --git a/docs/build/wallet-playbook/wallets/sponsorship/sponsor-smart.mdx b/docs/build/wallet-playbook/wallets/sponsorship/sponsor-smart.mdx new file mode 100644 index 000000000..cceba59da --- /dev/null +++ b/docs/build/wallet-playbook/wallets/sponsorship/sponsor-smart.mdx @@ -0,0 +1,50 @@ +--- +sidebar_label: "Sponsor smart wallets" +sidebar_position: 3 +--- + +# Sponsor Smart Wallets + +Smart Wallets use a different structure from Classic Wallets, which also makes the sponsorship process different. + +- **Classic Wallets** must hold a reserve of XLM based on account usage (e.g. account creation, adding trustlines). They also pay a small **Inclusion Fee** per transaction. +- **Smart Wallets** are contracts. They do not require reserves, but they pay both an [Inclusion Fee](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering#inclusion-fee) and a [Resource Fee](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering#resource-fee). The Resource Fee is calculated based on the resource consumption declared in the transaction, including storage, computation, and bandwidth. + +📖 Learn more about [Fees, Resource Limits, and Metering](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering) + +📖 Learn more about [Persisting Data in Smart Contracts](https://developers.stellar.org/docs/learn/fundamentals/contract-development/storage/persisting-data) + +📖 Learn more about [State Archival](https://developers.stellar.org/docs/learn/fundamentals/contract-development/storage/state-archival) + +## Sponsor a Smart Wallet + +To improve UX, these fees can be covered by a sponsoring account, so users don't need to hold XLM. This makes onboarding into smart wallets seamless. + +### Sponsoring With the Wallet Backend + +The [stellar/wallet-backend](https://github.com/stellar/wallet-backend) project provides server-side tooling to make user onboarding with smart wallets seamless. + +### Key Features + +- **Fee Sponsorship ("Gasless" UX)** + Uses **fee-bump transactions** so a distribution account pays transaction fees. +- **Channel Accounts** + Manages sequence numbers and scales throughput by using pre-funded channel accounts. +- **API Access** + Exposes endpoints for building, signing, and submitting transactions, secured by JWT-based authentication. + +### Sponsorship Flow + +1. **Frontend (Smart Wallet App)** + - User signs an operation according to their wallet's contract logic (e.g., passkey, policy signer). + - App sends the signed payload to the backend. + +2. **Backend (wallet-backend)** + - Builds the transaction using a **channel account** for sequence numbers. + - Wraps it in a **fee-bump transaction** so the **distribution account** pays the fee (and any reserve if needed). + - Returns the transaction to the frontend which can then submit it. + +3. **Result** + - User's wallet action succeeds. + - User never needed to hold XLM for fees or reserves. + - Sponsor absorbs costs and can manage them. diff --git a/docs/build/wallet-playbook/wallets/sponsorship/why-sponsor.mdx b/docs/build/wallet-playbook/wallets/sponsorship/why-sponsor.mdx new file mode 100644 index 000000000..2146d27a4 --- /dev/null +++ b/docs/build/wallet-playbook/wallets/sponsorship/why-sponsor.mdx @@ -0,0 +1,32 @@ +--- +sidebar_label: "Why use sponsorship" +sidebar_position: 1 +--- + +# Why use sponsorship + +Both **Classic** and **Smart Wallets** on the Stellar Network require **XLM** to be created and used, primarily to cover [fees](https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering) and reserve requirements. + +- **Classic wallets** must maintain a minimum **[base reserve](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#base-reserves)** of XLM to exist on the ledger. +- **Smart wallets** (e.g., contract-based `C` accounts) don’t require a base reserve, but they **incur fees** for contract deployment, ledger writes, and interactions. + +In both cases, wallets need to pay **fees** for operations such as transfers, contract calls, or trustline management. + +### The Onboarding Challenge + +If users are responsible for covering these costs, onboarding requires them to either **acquire XLM** or **receive it from an external source**, adding friction and complexity to users. To streamline the user experience, applications often aim to abstract this away so users don’t need to understand or even be aware of XLM. + +### Why Direct Funding Isn't Safe + +One option is to send XLM directly to a user’s wallet to cover creation and usage costs. However, this approach is **vulnerable to abuse**: malicious users could automate wallet creation and drain funds by creating multiple accounts. + +### Sponsorship Mechanisms + +Stellar provides **native fee and reserve sponsorship** for Classic wallets, enabling applications to cover costs securely: + +- **Fee Sponsorship** lets an application pay transaction fees on behalf of the user. +- **Reserve Sponsorship** lets an app lock the required XLM for account or trustline creation, _without transferring it_ to the user. + +This model avoids giving users direct control over XLM and protects the application from misuse, while enabling a seamless onboarding flow. + +On the other hand, Smart wallets don't require a base reserve, but they incur fees for contract deployment, ledger writes, and interactions. Tools like [Launchtube](https://github.com/stellar/launchtube) can be used to make this process easier. diff --git a/docs/build/wallet-playbook/wallets/wallet-types.mdx b/docs/build/wallet-playbook/wallets/wallet-types.mdx new file mode 100644 index 000000000..e9a40afdf --- /dev/null +++ b/docs/build/wallet-playbook/wallets/wallet-types.mdx @@ -0,0 +1,94 @@ +--- +sidebar_label: "Stellar Wallet Types" +sidebar_position: 1 +description: Learn about the two main types of wallets on Stellar—Classic Wallets and Smart Wallets—and how they differ in structure, capabilities, and implementation. +--- + +# Stellar Wallet Types + +Stellar supports two primary types of wallets: **Classic Wallets** and **Smart Wallets**. Both types are fully compatible with the Stellar network but differ significantly in state storage, transaction authorization, and their ability to interact with smart contracts. + +Your choice between wallet types will depend on your specific use case, desired user experience, and the degree of programmability you require. + +## Classic Wallets + +**Classic Wallets** utilize Stellar’s traditional [account model](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts), relying entirely on features native to the Stellar protocol. They do not leverage Soroban smart contracts. + +### Structure + +Classic Wallets: + +- Are backed by **Classic Stellar Accounts** (addresses beginning with G...) +- Employ **Ed25519 public/private keypairs** for [transaction signing](https://developers.stellar.org/docs/learn/fundamentals/transactions/signatures-multisig) +- Store account data ([called subentries](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#subentries)) directly within **Stellar Core** + +### Key Features + +Classic wallets natively support: + +- Sending and receiving XLM and other issued assets +- [Trustline management](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts#trustlines) +- Signer management (adding/removing signers) +- Trading via the Stellar Decentralized Exchange (DEX) +- Account or trustline sponsorship +- Data storage using the `ManageData` operation + +### Ideal Use Cases + +Classic wallets are suitable for: + +- Lightweight mobile and web wallets +- High-throughput, low-fee transactional applications +- Applications without complex on-chain logic requirements + +## [Smart Wallets](https://developers.stellar.org/docs/build/apps/smart-wallets): + +**Smart Wallets** leverage Stellar smart contracts, using programmable contract logic for transaction authorization and state management. This allows for fully customizable on-chain functionality. + +### Structure + +Smart Wallets: + +- Are backed by **Stellar Contract Accounts** +- Utilize contract logic for authorization rather than individual keys +- Can be created and initialized via external apps or directly by users + +### Key Features + +Smart wallets offer advanced functionality, including: + +- Customizable wallet behavior (social recovery, fee-splitting, delegation) +- Programmable transaction authorization with Soroban’s `require_auth` +- Interaction capabilities with other smart contracts (e.g., AMMs, bridges, payment distribution contracts) +- Support for alternative key schemes (e.g., secp256r1, passkeys) + +### Ideal Use Cases + +Smart wallets are ideal for: + +- Wallets requiring advanced access controls (e.g., social recovery, custom permissions) +- Wallets integrated directly with DeFi and on-chain financial applications +- Delegated signing mechanisms using external identity providers +- Applications needing robust on-chain business logic + +### Learn More + +- [Smart Wallets on Stellar](https://developers.stellar.org/docs/build/apps/smart-wallets/) + +## Classic vs Smart Wallet Comparison + +| Feature | Classic Wallet | Smart Wallet | +| -------------- | ------------------------- | ------------------------------ | +| Backed By | Stellar Core Account | Stellar Contract Account | +| Authorization | Keypair & multi-signature | Programmable via Soroban logic | +| On-Chain Logic | No | Yes | + +## Choosing the Right Wallet Type + +| Use Case | Recommended Wallet Type | +| --- | --- | +| Simple wallet for XLM and asset transfers | Classic Wallet | +| Social recovery and advanced permissions | Smart Wallet | +| Trading via Stellar DEX | Classic Wallet | +| Integration with Soroban smart contracts | Both supported at different levels | +| Low-cost user onboarding with sponsorship | Both supported | diff --git a/routes.txt b/routes.txt index 6fcb0de00..68a9b8ba2 100644 --- a/routes.txt +++ b/routes.txt @@ -168,6 +168,22 @@ /docs/build/smart-contracts/getting-started/setup /docs/build/smart-contracts/getting-started/storing-data /docs/build/smart-contracts/overview +/docs/build/wallet-playbook +/docs/build/wallet-playbook/infrastructure +/docs/build/wallet-playbook/infrastructure/onchain-data +/docs/build/wallet-playbook/introduction +/docs/build/wallet-playbook/key-management +/docs/build/wallet-playbook/key-management/key-management-providers +/docs/build/wallet-playbook/key-management/passkeys-and-smart-wallets +/docs/build/wallet-playbook/key-management/public-private-keys-overview +/docs/build/wallet-playbook/wallets +/docs/build/wallet-playbook/wallets/custody-models +/docs/build/wallet-playbook/wallets/sponsorship +/docs/build/wallet-playbook/wallets/sponsorship/estimate +/docs/build/wallet-playbook/wallets/sponsorship/sponsor-classic +/docs/build/wallet-playbook/wallets/sponsorship/sponsor-smart +/docs/build/wallet-playbook/wallets/sponsorship/why-sponsor +/docs/build/wallet-playbook/wallets/wallet-types /docs/category/anchor-integration /docs/category/build-a-payment-app-with-the-js-sdk /docs/category/build-a-wallet-with-the-wallet-sdk