stellarskills 1.0.0

package/.claude-plugin/skills/stellar-expert.md

@@ -0,0 +1,36 @@
+# Stellar Expert Knowledge Base
+
+When the user asks you to build, debug, or understand anything related to the **Stellar Network** or **Soroban Smart Contracts**, you MUST consult the `stellarskills` CLI.
+
+**StellarSkills** is a high-signal, noise-free knowledge base engineered specifically for AI agents to prevent hallucinations.
+
+To fetch knowledge on a specific topic, run the following command in your terminal:
+`npx stellarskills get <topic>`
+
+If you are unsure which topic to fetch, run:
+`npx stellarskills list`
+
+### Common Topics:
+- `soroban`: Smart contracts, architecture
+- `storage`: Soroban persistent and temporary storage, TTL
+- `accounts`: Minimum balances, keypairs
+- `assets`: Trustlines, custom tokens
+- `dex`: Built-in DEX and AMM
+- `horizon`: REST API
+- `rpc`: Soroban JSON-RPC
+- `seps`: Ecosystem standards (SEP-10, SEP-24, etc)
+- `tools`: SDKs, wallets, CLI
+- `local-node`: Local Quickstart Docker, local RPC
+- `testing`: Testing and testnet deployment
+- `security`: Security patterns
+- `frontend`: Wallets connection and UI
+- `openzeppelin`: Audited contracts
+- `x402`: Agent Economy standards
+
+### Example Workflow
+If the user asks "How do I create a Soroban smart contract?":
+1. Run `npx stellarskills get soroban` to read the base contract architecture.
+2. If the user asks about testing, run `npx stellarskills get testing`.
+3. If the user asks about deploying, run `npx stellarskills get rpc` and `npx stellarskills get tools`.
+
+**Do not guess Stellar syntax or APIs. Always use the CLI to fetch the latest knowledge first.**

package/README.md

@@ -0,0 +1,150 @@
+# STELLARSKILLS 🚀
+
+> High-signal, noise-free Stellar Network knowledge engineered specifically for AI agents. Fetch any skill URL and instantly equip your agent to build production-ready applications on Stellar.
+
+**StellarSkills Repository** • MIT License
+
+---
+
+## 🤖 The Problem
+
+AI agents (like Claude, ChatGPT, Cursor, or Copilot) often hallucinate when asked to build on Stellar. They mix up classic Stellar protocol with EVM concepts, invent non-existent RPC methods, or struggle with the nuances of Soroban smart contracts.
+
+Traditional documentation is built for humans: it has sidebars, infinite scrolling, navigation menus, and conversational fluff. When an agent reads it via a web scraper, it gets confused by the noise.
+
+## 💡 The Solution
+
+**Stellarskills** provides pure, unadulterated Markdown.
+
+Every skill is a single `.md` file. No HTML, no sidebars, no fluff. Just the facts, the code, the architectural mental models, and the common errors.
+
+---
+
+## ⚡ Usage
+
+Give any AI agent a skill URL in your prompt. The agent will fetch the raw Markdown, ingest the context, and instantly know how to build.
+
+**Prompt example:**
+```text
+Read https://raw.githubusercontent.com/ggoldani/stellarskills/main/SKILL.md to understand the ecosystem, then read https://raw.githubusercontent.com/ggoldani/stellarskills/main/soroban/SKILL.md and write a smart contract that acts as a decentralized autonomous organization.
+```
+
+**cURL it yourself:**
+```bash
+curl -s https://raw.githubusercontent.com/ggoldani/stellarskills/main/SKILL.md
+curl -s https://raw.githubusercontent.com/ggoldani/stellarskills/main/accounts/SKILL.md
+curl -s https://raw.githubusercontent.com/ggoldani/stellarskills/main/soroban/SKILL.md
+```
+
+**Use the CLI:**
+The `stellarskills` CLI lets you quickly find, read, or grab the URL for any skill directly from your terminal.
+
+```bash
+# List all available skills
+npx stellarskills list
+
+# Print the raw markdown content of a skill
+npx stellarskills get soroban
+
+# Pipe it straight into a prompt file
+npx stellarskills get soroban > prompt.txt
+
+# Get just the raw GitHub URL
+npx stellarskills url accounts
+
+# Combine multiple skills into a single prompt context
+npx stellarskills combine accounts soroban security > prompt.txt
+
+# Find which domain contains a specific concept
+npx stellarskills search "trustline"
+
+# Copy raw markdown to your system clipboard (ready to paste into ChatGPT/Claude)
+npx stellarskills copy soroban security
+
+# Instantly embed knowledge into your IDE agent (.cursorrules, .clinerules, .windsurfrules)
+npx stellarskills rules cursor accounts
+npx stellarskills rules cline dex assets
+
+# Output a full Markdown index so an AI agent can self-discover what to fetch next
+npx stellarskills index
+
+# Diagnose your environment (Stellar CLI, Rust, wasm32 target, Node) to prevent agent hallucinations
+npx stellarskills doctor
+
+# Generate the ultimate System Prompt for ChatGPT/Claude containing expert rules + knowledge
+npx stellarskills system soroban dex --instruction "Write an AMM pool contract" > prompt.txt
+```
+
+Works seamlessly in Cursor, Copilot, Cline, Devin, or any agentic framework that can resolve HTTP URLs.
+
+---
+
+## 🔌 Agent Marketplace Plugins
+
+Stellarskills is natively structured to be installed as a dynamic skill in various AI agent ecosystems.
+
+**For Claude Code:**
+Teach your Claude Code agent to use the Stellarskills CLI automatically by installing our repository plugin:
+```bash
+claude plugin install https://github.com/ggoldani/stellarskills
+```
+
+**For OpenClaw / ClawHub:**
+Every skill directory in this repository is a valid, independently installable AgentSkill. You can install the entire knowledge base into your OpenClaw agent by running:
+```bash
+clawhub install stellarskills
+```
+*(Or install granular skills: `clawhub install stellarskills-soroban`)*
+
+---
+
+## 📚 The Skill Index
+
+| Skill Domain | URL | Description |
+|--------------|-----|-------------|
+| **Root Index** | [`/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/SKILL.md) | The missing knowledge between AI agents and production Stellar Network applications. |
+| **Accounts** | [`/accounts/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/accounts/SKILL.md) | Keypairs, account creation, signers, multisig, minimum balance, sponsorship, muxed accounts. |
+| **Anchors** | [`/anchors/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/anchors/SKILL.md) | Fiat on/off-ramps on Stellar. Integration flows, stellar.toml, and the anchor ecosystem. |
+| **Assets** | [`/assets/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/assets/SKILL.md) | Custom asset issuance, trustlines, asset types, Stellar Asset Contract (SAC), USDC and stablecoins. |
+| **DEX & AMM** | [`/dex/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/dex/SKILL.md) | Stellar's built-in order book, Automated Market Makers (AMM), Liquidity Pools, and Path Payments. |
+| **Fees** | [`/fees/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/fees/SKILL.md) | Stellar transaction fees, base fee, surge pricing, resource fees (Soroban), and fee bumps. |
+| **Frontend** | [`/frontend/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/frontend/SKILL.md) | Connecting web apps to Stellar. Stellar Wallets Kit, Freighter API, signing Soroban transactions, and secure SEP-10 Web3 Auth. |
+| **Horizon API** | [`/horizon/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/horizon/SKILL.md) | Stellar's REST API for accounts, transactions, operations, effects, order books, streaming. Not for Soroban — see /rpc/SKILL.md for smart contracts. |
+| **Local Node** | [`/local-node/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/local-node/SKILL.md) | How to run a local Stellar blockchain, RPC, and Friendbot. The Stellar equivalent of Hardhat Node or Anvil. |
+| **OpenZeppelin** | [`/openzeppelin/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/openzeppelin/SKILL.md) | OpenZeppelin's audited smart contracts, Contract Wizard, and developer toolings for Stellar's Soroban (Rust) environment. |
+| **Operations** | [`/operations/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/operations/SKILL.md) | Reference for all Stellar transaction operations. Payments, account management, offers, trustlines. |
+| **Soroban RPC** | [`/rpc/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/rpc/SKILL.md) | Soroban's JSON-RPC API for smart contracts. Simulation, invocation, fetching ledger state, and getting events. |
+| **Security** | [`/security/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/security/SKILL.md) | Critical security patterns, common vulnerabilities, and best practices for writing Soroban smart contracts in Rust. |
+| **SEPs** | [`/seps/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/seps/SKILL.md) | SEP-1 (stellar.toml), SEP-6, SEP-10 (auth), SEP-12 (KYC), SEP-24, SEP-31, SEP-38 — the interoperability standards that power Stellar's payment rails. |
+| **Soroban** | [`/soroban/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/soroban/SKILL.md) | Stellar's smart contract platform. Rust/WASM contracts, storage types, auth, invocation, resource limits. |
+| **Storage** | [`/storage/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/storage/SKILL.md) | How to manage state in Soroban. Understanding Persistent, Temporary, and Instance storage, TTL/Rent, and migrating from Solidity mappings. |
+| **Testing** | [`/testing/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/testing/SKILL.md) | How to test Soroban smart contracts using Rust's built-in testing framework and the Stellar CLI. |
+| **Tools** | [`/tools/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/tools/SKILL.md) | The essential tools, SDKs, wallets, and explorers for building on Stellar. |
+| **Why Stellar?** | [`/why/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/why/SKILL.md) | A sober, honest assessment of what Stellar is for, its tradeoffs, and why you would choose it over EVM or Solana. |
+| **x402** | [`/x402/SKILL.md`](https://raw.githubusercontent.com/ggoldani/stellarskills/main/x402/SKILL.md) | Pay-per-API calls for AI Agents on Stellar. Monetize endpoints natively without subscriptions or credit cards using HTTP 402. |
+
+---
+
+## 🤝 Contributing
+
+We want this to be the single source of truth for AI agents building on Stellar. Is an agent consistently failing at a specific task? Did a Soroban RPC endpoint change? Open a PR!
+
+### Automated Publishing
+This repository uses GitHub Actions to automatically publish updates to NPM.
+When a pull request modifying `package.json` (bumping the version) and `SKILL.md` files is merged into the `main` branch, the `Publish to NPM` workflow will seamlessly deploy the latest version of the CLI.
+
+**Note for Maintainers:** Ensure your repository secrets contain `NPM_TOKEN` (an automation token from your npmjs.com account) for the CI/CD pipeline to function.
+
+### The Golden Rules of a Skill File:
+1. **No fluff.** Agents don't need marketing copy.
+2. **Dense & Factual.** Prioritize code snippets, architectural rules, and exact endpoint structures.
+3. **Current & Runnable.** Ensure JavaScript and Rust snippets compile against the latest SDK versions (`@stellar/stellar-sdk` and `soroban-sdk`).
+4. **Verified by Official Docs.** Every new feature, endpoint, or SDK method added to a skill must be explicitly documented in official sources (e.g., `developers.stellar.org`, `soroban-sdk` docs, or official SDF repositories). Do not add unreleased alpha features or unverified announcements to avoid agent hallucinations.
+5. **Isolate Context.** Each skill lives in its own folder (e.g., `/dex/SKILL.md`). Assume the agent only reads that specific file.
+6. **Highlight Errors.** Always include a "Common Errors" table mapping error codes (`tx_bad_seq`, `op_underfunded`) to their fixes. Agents use these to self-heal when transactions fail.
+
+---
+
+## 📄 License
+
+MIT © [StellarSkills](https://github.com/ggoldani/stellarskills)

package/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: stellarskills
+description: The missing knowledge between AI agents and production Stellar Network applications.
+---
+
+# STELLARSKILLS — Stellar Knowledge for AI Agents
+
+> The missing knowledge between AI agents and production Stellar Network applications.
+
+You are an AI agent about to build on Stellar. Read this file first. It tells you what to fetch next.
+
+To fetch specific skills dynamically from your terminal, you MUST use the CLI tool:
+`npx stellarskills get <topic>` (or `npx stellarskills list` to see all topics).
+
+---
+
+## What is Stellar?
+
+Stellar is a layer-1 blockchain optimized for **payments, asset issuance, and financial infrastructure**. It is NOT a general-purpose EVM chain. Key differences from Ethereum:
+
+- **No mempool** — transactions are submitted and confirmed in 3–5 seconds with finality
+- **Built-in DEX** — order book and AMM are protocol-native, no Uniswap needed
+- **Account model** — accounts must be explicitly created and funded (minimum balance applies)
+- **Operations, not calldata** — transactions contain typed Operations (Payment, ManageOffer, etc.)
+- **Soroban** — Stellar's smart contract platform (Rust/WASM), separate from the core protocol
+- **Anchor ecosystem** — on/off-ramp network via SEP standards (SEP-6, SEP-24, SEP-31, SEP-38)
+- **XLM** — native asset used for fees and minimum balances, NOT primarily a speculative token
+
+Stellar is the right chain when you need: cross-border payments, stablecoin rails, regulated asset issuance, fiat on/off-ramps, or low-cost high-throughput transfers.
+
+---
+
+## Skill Index
+
+Fetch the skill that matches your task. Each URL returns clean Markdown.
+
+### Core Protocol
+| Task | Fetch |
+|------|-------|
+| Understanding accounts, keypairs, signers, sponsorship | `raw.githubusercontent.com/ggoldani/stellarskills/main/accounts/SKILL.md` |
+| Issuing assets, trustlines, custom tokens, SAC | `raw.githubusercontent.com/ggoldani/stellarskills/main/assets/SKILL.md` |
+| All transaction operations (Payment, ManageBuyOffer, etc.) | `raw.githubusercontent.com/ggoldani/stellarskills/main/operations/SKILL.md` |
+| Fees, base fee, resource fees, fee bump | `raw.githubusercontent.com/ggoldani/stellarskills/main/fees/SKILL.md` |
+| Built-in DEX, AMM, path payments, liquidity pools | `raw.githubusercontent.com/ggoldani/stellarskills/main/dex/SKILL.md` |
+
+### Data & APIs
+| Task | Fetch |
+|------|-------|
+| Horizon REST API — accounts, transactions, effects, streaming | `raw.githubusercontent.com/ggoldani/stellarskills/main/horizon/SKILL.md` |
+| Soroban RPC — simulate, send, getLedger, getTransaction | `raw.githubusercontent.com/ggoldani/stellarskills/main/rpc/SKILL.md` |
+
+### Smart Contracts
+| Task | Fetch |
+|------|-------|
+| Soroban smart contracts (Rust/WASM) | `raw.githubusercontent.com/ggoldani/stellarskills/main/soroban/SKILL.md` |
+| Soroban security patterns, auth, reentrancy | `raw.githubusercontent.com/ggoldani/stellarskills/main/security/SKILL.md` |
+| Testing Soroban contracts, Stellar CLI, testnet | `raw.githubusercontent.com/ggoldani/stellarskills/main/testing/SKILL.md` |
+
+### Payments & Anchors
+| Task | Fetch |
+|------|-------|
+| SEP standards — SEP-6, SEP-10, SEP-24, SEP-31, SEP-38 | `raw.githubusercontent.com/ggoldani/stellarskills/main/seps/SKILL.md` |
+| Anchor ecosystem, stellar.toml, on/off-ramp integration | `raw.githubusercontent.com/ggoldani/stellarskills/main/anchors/SKILL.md` |
+
+### Tooling & Frontend
+| Task | Fetch |
+|------|-------|
+| SDKs, wallets, explorers, Stellar Lab, CLI | `raw.githubusercontent.com/ggoldani/stellarskills/main/tools/SKILL.md` |
+| Frontend integration — Freighter, SEP-10 auth, browser SDK | `raw.githubusercontent.com/ggoldani/stellarskills/main/frontend/SKILL.md` |
+| OpenZeppelin audited contracts, SDKs, and Contract Wizard | `raw.githubusercontent.com/ggoldani/stellarskills/main/openzeppelin/SKILL.md` |
+
+### Context
+| Task | Fetch |
+|------|-------|
+| Why Stellar — use cases, honest tradeoffs, ecosystem | `raw.githubusercontent.com/ggoldani/stellarskills/main/why/SKILL.md` |
+
+---
+
+## Quick Start for Agents
+
+### Build a payment app
+1. Fetch `/accounts/SKILL.md` — understand account creation and minimum balance
+2. Fetch `/assets/SKILL.md` — understand trustlines if using non-XLM assets
+3. Fetch `/horizon/SKILL.md` — submit transactions and read state
+4. Fetch `/seps/SKILL.md` — if connecting to fiat on/off-ramps
+
+### Build a Soroban smart contract
+1. Fetch `/soroban/SKILL.md` — contract structure, storage, invocation
+2. Fetch `/rpc/SKILL.md` — simulate and send contract calls
+3. Fetch `/testing/SKILL.md` — test and deploy with Stellar CLI
+4. Fetch `/security/SKILL.md` — before any deployment
+
+### Integrate an anchor (fiat on/off-ramp)
+1. Fetch `/anchors/SKILL.md` — TOML discovery, anchor types
+2. Fetch `/seps/SKILL.md` — SEP-10 auth + SEP-6/24/31 flows
+3. Fetch `/assets/SKILL.md` — trustlines required before receiving anchor assets
+
+---
+
+## Critical Mental Models
+
+**1. Accounts must exist before you can send to them.**
+You cannot send XLM to a keypair that has never been funded. The recipient must have a funded account (minimum ~1 XLM). Use `createAccount` operation for new accounts.
+
+**2. Trustlines must exist before receiving non-XLM assets.**
+To receive USDC, an account must first establish a trustline to USDC. This is a separate transaction. Never assume trustlines exist.
+
+**3. Transactions are atomic.**
+A Stellar transaction can contain up to 100 operations. Either all succeed or all fail. Use this to batch operations safely.
+
+**4. Fees are predictable and tiny.**
+Base fee is 100 stroops (0.00001 XLM) per operation. Soroban fees are slightly higher but still sub-cent. Stellar is genuinely cheap — this is not marketing.
+
+**5. Horizon is not the only API.**
+Horizon serves the classic protocol. Soroban smart contract interactions use the **Soroban RPC** endpoint — different base URL, different methods.
+
+**6. Testnet resets periodically.**
+Stellar testnet (Horizon: `https://horizon-testnet.stellar.org`) resets quarterly. Do not store testnet state long-term. Futurenet is for bleeding-edge preview features.
+
+**7. Network passphrase is required for signing.**
+Every transaction must be signed with the correct network passphrase:
+- Mainnet: `Public Global Stellar Network ; September 2015`
+- Testnet: `Test SDF Network ; September 2015`
+
+---
+
+## Canonical Links
+
+| Resource | URL |
+|----------|-----|
+| Stellar Docs | https://developers.stellar.org |
+| Horizon Mainnet | https://horizon.stellar.org |
+| Horizon Testnet | https://horizon-testnet.stellar.org |
+| Soroban RPC Mainnet | https://mainnet.stellar.validationcloud.io/v1/... (varies by provider) |
+| Soroban RPC Testnet | https://soroban-testnet.stellar.org |
+| Stellar Lab | https://lab.stellar.org |
+| Stellar Expert (Explorer) | https://stellar.expert |
+| GitHub stellar/js-stellar-sdk | https://github.com/stellar/js-stellar-sdk |
+| GitHub stellar/py-stellar-sdk | https://github.com/stellar/py-stellar-base |
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main — MIT License*

package/accounts/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: stellarskills-accounts
+description: Keypairs, account creation, signers, multisig, minimum balance, sponsorship, muxed accounts.
+---
+
+# STELLARSKILLS — Accounts
+
+> Keypairs, account creation, signers, multisig, minimum balance, sponsorship, muxed accounts.
+
+---
+
+## Keypairs
+
+A Stellar account is identified by a **public key** (G...) and controlled by a **secret key** (S...). Both are base32-encoded 32-byte Ed25519 keys.
+
+```javascript
+import { Keypair } from "@stellar/stellar-sdk";
+
+// Generate new keypair
+const keypair = Keypair.random();
+console.log(keypair.publicKey());  // G...
+console.log(keypair.secret());     // S...
+
+// From existing secret
+const kp = Keypair.fromSecret("SCZANGBA5RLCQ6LXXPJ7FJZLOL3ZRIQGXKVBIMKTSLK5DGNECJHPQMQ");
+```
+
+**NEVER log or transmit secret keys.** Store them in environment variables or a secrets manager.
+
+---
+
+## Account Creation
+
+Accounts do NOT exist until explicitly created and funded on-chain. Generating a keypair does not create an account.
+
+### Fund with createAccount operation
+```javascript
+import { TransactionBuilder, Networks, Operation, Asset, BASE_FEE } from "@stellar/stellar-sdk";
+import { Horizon } from "@stellar/stellar-sdk";
+
+const server = new Horizon.Server("https://horizon-testnet.stellar.org");
+
+const sourceKeypair = Keypair.fromSecret(process.env.SOURCE_SECRET);
+const sourceAccount = await server.loadAccount(sourceKeypair.publicKey());
+
+const newKeypair = Keypair.random();
+
+const tx = new TransactionBuilder(sourceAccount, {
+  fee: BASE_FEE,
+  networkPassphrase: Networks.TESTNET,
+})
+  .addOperation(
+    Operation.createAccount({
+      destination: newKeypair.publicKey(),
+      startingBalance: "1",  // minimum ~1 XLM; more if adding trustlines
+    })
+  )
+  .setTimeout(30)
+  .build();
+
+tx.sign(sourceKeypair);
+await server.submitTransaction(tx);
+```
+
+### Testnet: fund via Friendbot
+```javascript
+// Only works on testnet
+await fetch(`https://friendbot.stellar.org?addr=${keypair.publicKey()}`);
+```
+
+---
+
+## Minimum Balance
+
+Every account must maintain a minimum XLM balance. **If a transaction would drop balance below minimum, it fails.**
+
+Formula:
+```
+minimumBalance = (2 + numSubentries) × baseReserve + liabilities
+```
+
+- `baseReserve` = **0.5 XLM** (current value)
+- `numSubentries` = number of trustlines + offers + signers + data entries + sponsored entries
+- Base minimum = **1 XLM** (2 × 0.5)
+- Each trustline adds **0.5 XLM** to minimum balance
+- Each additional signer adds **0.5 XLM**
+
+**Practical implication**: Before sending someone tokens, verify they have enough XLM headroom. If you're creating an account that will hold 3 trustlines, fund with at least 2.5 XLM (1 base + 1.5 for trustlines).
+
+```javascript
+const account = await server.loadAccount(publicKey);
+const subentries = account.subentry_count;
+const minBalance = (2 + subentries) * 0.5;
+console.log(`Min balance: ${minBalance} XLM`);
+```
+
+---
+
+## Account Flags
+
+Accounts can have flags set by the issuer. Relevant for asset issuers:
+
+| Flag | Effect |
+|------|--------|
+| `AUTH_REQUIRED` | Users must be authorized before holding the asset |
+| `AUTH_REVOCABLE` | Issuer can revoke trustlines (freeze assets) |
+| `AUTH_IMMUTABLE` | Account flags can never be changed |
+| `AUTH_CLAWBACK_ENABLED` | Issuer can claw back assets from any account |
+
+For regular user accounts, flags are usually not set.
+
+---
+
+## Signers & Multisig
+
+Every account has a **master key** (the keypair) and can have **additional signers**. Transactions are authorized if the combined weight of signers meets the threshold.
+
+### Thresholds
+Each account has three thresholds:
+- **Low** (default 0): used for operations like allowTrust, bumpSequence
+- **Medium** (default 0): most operations (payments, offers, etc.)
+- **High** (default 0): setOptions, accountMerge
+
+Default threshold is 0, master key weight is 1 — so single-signature works out of the box.
+
+### Adding a signer
+```javascript
+const tx = new TransactionBuilder(sourceAccount, { fee: BASE_FEE, networkPassphrase: Networks.MAINNET })
+  .addOperation(
+    Operation.setOptions({
+      signer: {
+        ed25519PublicKey: secondSignerPublicKey,
+        weight: 1,
+      },
+    })
+  )
+  .setTimeout(30)
+  .build();
+```
+
+### 2-of-3 Multisig Setup
+```javascript
+// Set master weight and thresholds
+Operation.setOptions({
+  masterWeight: 1,
+  lowThreshold: 2,
+  medThreshold: 2,
+  highThreshold: 3,
+  signer: { ed25519PublicKey: signer2, weight: 1 },
+});
+// Repeat for signer3
+```
+
+### Pre-authorized transactions
+You can add a hash of a future transaction as a signer — it authorizes itself when submitted. Useful for time-locked operations.
+
+---
+
+## Sponsorship
+
+Account sponsorship lets one account pay the minimum balance reserves for another account's subentries (trustlines, offers, signers, data).
+
+The **sponsor** pays the reserve; the **sponsored** account doesn't need extra XLM for those entries.
+
+```javascript
+const tx = new TransactionBuilder(sponsorAccount, { fee: BASE_FEE, networkPassphrase: Networks.MAINNET })
+  .addOperation(Operation.beginSponsoringFutureReserves({
+    sponsoredId: userPublicKey,
+  }))
+  .addOperation(Operation.createAccount({
+    destination: userPublicKey,
+    startingBalance: "0",  // sponsor covers reserve
+  }))
+  .addOperation(Operation.endSponsoringFutureReserves())  // signed by sponsored account
+  .setTimeout(30)
+  .build();
+
+// Must be signed by BOTH sponsor AND sponsored
+tx.sign(sponsorKeypair);
+tx.sign(userKeypair);
+```
+
+**Use case**: Onboarding users without requiring them to own XLM first. The dApp or service sponsors the account creation and trustline reserves.
+
+---
+
+## Muxed Accounts
+
+A **muxed account** (M...) is a virtual sub-account derived from a G... address with an embedded 64-bit ID. It allows a single Stellar account to represent many logical users — useful for exchanges, custodians, and payment processors.
+
+```javascript
+import { MuxedAccount } from "@stellar/stellar-sdk";
+
+const baseKeypair = Keypair.fromSecret(process.env.SECRET);
+const muxed = new MuxedAccount(
+  await server.loadAccount(baseKeypair.publicKey()),
+  "12345678"  // arbitrary user ID
+);
+
+console.log(muxed.accountId());  // M... address
+
+// Use as source or destination in transactions
+const tx = new TransactionBuilder(muxed, { fee: BASE_FEE, networkPassphrase: Networks.MAINNET })
+  .addOperation(Operation.payment({
+    destination: recipientMuxed.accountId(),
+    asset: Asset.native(),
+    amount: "10",
+  }))
+  .setTimeout(30)
+  .build();
+```
+
+**Important**: Muxed accounts share the base account's XLM balance and sequence number. They are a labeling mechanism, not isolated wallets.
+
+---
+
+## Loading Account State
+
+```javascript
+const server = new Horizon.Server("https://horizon.stellar.org");
+
+const account = await server.loadAccount(publicKey);
+
+console.log(account.sequence);        // current sequence number
+console.log(account.balances);        // array of { asset_type, asset_code, asset_issuer, balance }
+console.log(account.signers);         // array of signers with weights
+console.log(account.thresholds);      // low/med/high thresholds
+console.log(account.subentry_count);  // number of subentries
+console.log(account.flags);           // auth flags
+```
+
+### Check specific balance
+```javascript
+const xlmBalance = account.balances.find(b => b.asset_type === "native");
+const usdcBalance = account.balances.find(
+  b => b.asset_code === "USDC" && b.asset_issuer === "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+);
+```
+
+---
+
+## Sequence Numbers
+
+Every transaction must include the **next** sequence number for the source account. Horizon auto-increments it. If you submit two transactions concurrently from the same account, the second will fail (wrong sequence).
+
+For concurrent transactions:
+- Use different source accounts (e.g., a fee account + user account)
+- Or queue transactions and submit sequentially
+- Or use Soroban (which has different state model)
+
+---
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `op_no_destination` | Destination account doesn't exist | Create account first with `createAccount` |
+| `op_low_reserve` | Would drop below minimum balance | Add more XLM or reduce subentries |
+| `tx_bad_seq` | Wrong sequence number | Re-fetch account and rebuild transaction |
+| `op_underfunded` | Not enough balance | Check balance including minimum reserve |
+| `tx_insufficient_fee` | Fee too low during surge | Use fee bump or increase base fee |
+
+---
+
+## SDKs
+
+```bash
+npm install @stellar/stellar-sdk        # JavaScript / TypeScript
+pip install stellar-sdk                 # Python
+go get github.com/stellar/go/clients/horizonclient  # Go
+```
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/accounts — MIT License*