Add wallet playbook to docs

config/theme/navbar.ts

@@ -35,7 +35,12 @@ const build: NavbarItem = {
     },
     {
       type: 'html',
-      value: '<hr><a href="/docs/build/apps" class="subtitle"><small>Build Applications</small>',
+      value: '<hr><a href="/docs/build/wallet-playbook" class="subtitle"><small>Stellar Wallet Playbook</small>',
+      className: 'subtitle',
+    },
+    {
+      type: 'html',
+      value: '<hr><a href="/docs/build/apps" class="subtitle"><small>Application Tutorials</small>',
       className: 'subtitle',
     },
     {

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.
 
 <DocCardList />

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

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.
+
+<DocCardList />

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.
+
+<DocCardList />

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

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

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.
+
+<DocCardList />

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

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)

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.

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.
+
+<DocCardList />

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.
+
+:::

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.
+
+<DocCardList />

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.
+
+:::