stellarskills 1.0.0

package/tools/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: stellarskills-tools
+description: The essential tools, SDKs, wallets, and explorers for building on Stellar.
+---
+
+# STELLARSKILLS — Tools & SDKs
+
+> The essential tools, SDKs, wallets, and explorers for building on Stellar.
+
+---
+
+## SDKs (Software Development Kits)
+
+SDF officially maintains or heavily supports these SDKs for interacting with Horizon and Soroban RPC.
+
+| Language | Package | Purpose |
+|----------|---------|---------|
+| **JavaScript / TS** | `@stellar/stellar-sdk` | Everything. Wallets, backend, frontend. |
+| **Rust** | `soroban-sdk` | Writing Soroban smart contracts. |
+| **Python** | `stellar-sdk` | Backend automation, data science. |
+| **Go** | `github.com/stellar/go` | High-performance backend services. |
+| **Java** | `java-stellar-sdk` | Enterprise backends, Android. |
+| **Flutter / Dart** | `stellar_flutter_sdk` | Mobile app development. |
+| **iOS / Swift** | `stellar-ios-mac-sdk` | iOS app development. |
+
+### JS SDK Pro Tip
+The JS SDK is split conceptually but bundled together:
+- `Keypair`, `TransactionBuilder`, `Operation` (Core XDR building)
+- `Horizon.Server` (Classic protocol REST API)
+- `SorobanRpc.Server` (Smart contract JSON-RPC)
+
+---
+
+## Developer Tools
+
+### 1. Stellar CLI
+The Swiss Army knife for Soroban and Stellar development. Written in Rust.
+```bash
+cargo install --locked stellar-cli --features opt
+
+# Manage identities
+stellar keys generate alice
+
+# Fund on testnet
+stellar keys fund alice
+
+# Build and optimize contracts
+stellar contract build
+stellar contract optimize --wasm target/.../my_contract.wasm
+
+# Deploy and invoke contracts
+stellar contract deploy --wasm ... --source alice --network testnet
+stellar contract invoke --id C... --source alice --network testnet -- func_name --arg value
+```
+
+### 2. Stellar Lab
+A GUI for exploring the network, building transactions manually, and signing them. Excellent for debugging XDR.
+**URL**: `https://lab.stellar.org`
+
+### 3. Friendbot
+The testnet faucet. Funds an account with 10,000 testnet XLM.
+```bash
+curl "https://friendbot.stellar.org?addr=G..."
+```
+
+---
+
+## Explorers
+
+To view ledgers, accounts, transactions, and assets on-chain.
+
+| Explorer | URL | Best For |
+|----------|-----|----------|
+| **Stellar Expert** | `https://stellar.expert` | The gold standard. Asset stats, AMM pools, contract invocations, SEP discovery. |
+| **Steexp** | `https://steexp.com` | Simple, fast ledger exploration. |
+
+---
+
+## Wallets (for Developers)
+
+To test your dApp, you need a wallet that supports Soroban and WalletConnect.
+
+| Wallet | Platform | Notes |
+|--------|----------|-------|
+| **Freighter** | Browser Extension | The MetaMask of Stellar. Built by SDF. Essential for testing web dApps. Supports testnet, futurenet, mainnet. |
+| **Lobstr** | Mobile / Web | The most popular consumer wallet. Supports classic assets, DEX, and WalletConnect. |
+| **Vibrant** | Mobile | USDC-centric consumer wallet. Good for testing SEP-24 fiat rails. |
+
+---
+
+## RPC & Horizon Providers
+
+You shouldn't use the SDF public endpoints (`horizon.stellar.org`) for heavy production traffic. Use a commercial provider:
+
+- **Validation Cloud** (RPC, Horizon)
+- **Blockdaemon** (RPC, Horizon)
+- **Tatum** (Horizon)
+- **QuickNode** (Horizon, RPC coming soon)
+
+---
+
+## Open Source Reference Projects
+
+When you don't know how to implement something, look here:
+
+- **Polaris** (`stellar/django-polaris`): Reference implementation for Anchors (SEPs).
+- **Soroban Example dApp** (`stellar/soroban-example-dapp`): End-to-end React + Soroban contract example.
+- **Freighter API** (`stellar/freighter`): How the browser extension works.
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/tools — MIT License*

package/why/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: stellarskills-why
+description: A sober, honest assessment of what Stellar is for, its tradeoffs, and why you would choose it over EVM or Solana.
+---
+
+# STELLARSKILLS — Why Stellar?
+
+> A sober, honest assessment of what Stellar is for, its tradeoffs, and why you would choose it over EVM or Solana.
+
+---
+
+## Stellar's Thesis
+
+Stellar was built in 2014 with a specific, narrow thesis: **Provide the infrastructure for global payments and asset issuance.**
+
+It is not trying to be a world computer. It is not trying to host the next big decentralized social network. It is trying to be the rails that money moves on.
+
+### The Sweet Spot
+You should build on Stellar if your application involves:
+- Cross-border remittances.
+- B2B payments.
+- Fiat stablecoins (USDC, EURC, etc.) and tokenized RWAs (Real World Assets).
+- Regulated asset issuance (where the issuer needs freeze/clawback capabilities).
+- Treasury management and payroll.
+- On/off-ramps to the traditional banking system.
+
+---
+
+## Technical Tradeoffs
+
+### 1. Throughput & Finality
+- **Stellar**: ~1000 tx/sec (classic), 3-5 second block times. **Instant finality.** Because it uses SCP (Stellar Consensus Protocol, a federated Byzantine agreement algorithm) rather than Proof of Work or Proof of Stake, there are no forks. Once a transaction is in a ledger, it cannot be rolled back.
+- **EVM/L2s**: Variable finality (often minutes or days for absolute settlement on L1).
+
+### 2. The Mempool
+- **Stellar**: There is no public mempool. Transactions are submitted directly to Horizon/RPC, broadcast to validators, and included in the next 5-second ledger. This eliminates MEV (Miner Extractable Value) like front-running and sandwich attacks.
+- **Ethereum/Solana**: Public mempool creates a dark forest of MEV bots.
+
+### 3. State Management (Accounts vs Wallets)
+- **Stellar**: An account must explicitly be funded (minimum balance of 1 XLM) and must explicitly opt-in to receive an asset (Trustlines). This prevents spam tokens from being airdropped into your wallet without permission.
+- **EVM**: Anyone can send any ERC-20 to any address.
+
+### 4. Smart Contracts (Soroban)
+- **Stellar**: Rust-based, WASM execution, explicit resource metering, explicitly isolated storage. Designed for safety and predictable pricing.
+- **EVM**: Solidity, global mutable state, implicit auth. Designed for maximum composability but prone to reentrancy and state bloat.
+
+### 5. The Built-in DEX
+- **Stellar**: Limit order books and AMMs are native to the protocol. You don't interact with a smart contract to trade; you just submit an Operation.
+- **EVM**: All trading happens via third-party smart contracts (Uniswap, 1inch).
+
+---
+
+## The Interoperability Standard (SEPs)
+
+The biggest reason fintechs choose Stellar is the **SEP (Stellar Ecosystem Proposal)** framework.
+
+If you build a wallet on Ethereum, integrating a fiat on-ramp means signing a bespoke business deal with MoonPay or Ramp, reading their custom API docs, and implementing their specific flow.
+
+On Stellar, fiat on/off-ramps (Anchors) all follow the exact same API standards (SEP-24, SEP-6, SEP-31). A wallet developer writes the integration code *once*, and instantly supports cashing in/out across dozens of countries (USDC in the US, ARST in Argentina, BRL in Brazil, NGN in Nigeria) without changing a line of code.
+
+---
+
+## When NOT to use Stellar
+
+Do not use Stellar if:
+1. You want to build a high-frequency trading on-chain game.
+2. You need to store large amounts of arbitrary data on-chain.
+3. You rely on deep, complex smart contract composability (e.g., flash loans nested through 5 different DeFi protocols).
+4. Your primary go-to-market strategy relies on "degen" memecoin speculation.
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/why — MIT License*

package/x402/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: stellarskills-x402
+description: Pay-per-API calls for AI Agents on Stellar. Monetize endpoints natively without subscriptions or credit cards using HTTP 402.
+---
+
+# STELLARSKILLS — x402 Protocol (Agent Economy)
+
+> Pay-per-API calls for AI Agents on Stellar. Monetize endpoints natively without subscriptions or credit cards using HTTP 402.
+
+> ⚠️ **CUTTING EDGE TECH:** The x402 protocol on Stellar is extremely new. The SDKs and middleware patterns shown here may change rapidly. Always verify against the latest Coinbase/Stellar x402 documentation and contribute updates via PR!
+
+---
+
+## 1. What is x402?
+
+x402 revives the reserved `402 Payment Required` HTTP status code. It allows servers to monetize endpoints per-request and allows clients (especially autonomous AI Agents) to pay for that request natively using digital assets (like USDC) on the Stellar Network.
+
+Instead of a human signing up for a subscription tier and providing a credit card, an AI Agent can dynamically pay 1/100th of a cent via a Stellar micropayment every time it hits your API.
+
+### The Flow
+1. **Client** requests a protected resource.
+2. **Server** responds with HTTP `402` and payment requirements.
+3. **Client** signs a Stellar payment transaction using their keypair (with Soroban auth).
+4. **Client** retries the request with the signed payment in the `X-PAYMENT` header.
+5. **Server** verifies the payment via a facilitator, settles on Stellar, and returns the resource.
+
+---
+
+## 2. Server Integration (Selling Access)
+
+To protect an API endpoint, use the x402 payment middleware. The middleware intercepts the request and handles the 402 rejection and the subsequent payment verification automatically.
+
+```bash
+npm install stellar-x402 express
+```
+
+```javascript
+import express from 'express';
+import { paymentMiddleware } from 'stellar-x402/server';
+
+const app = express();
+
+// Protect a specific route
+app.use(
+  '/api/premium-data',
+  paymentMiddleware({
+    // Configuration dictates price and the Stellar address receiving the payment
+    token: 'USDC',
+    amount: '0.05',
+    recipient: process.env.STELLAR_MERCHANT_PUBLIC_KEY
+  })
+);
+
+app.get('/api/premium-data', (req, res) => {
+  // This block only executes if the client successfully paid
+  res.json({ secret: "AI agents rule the world" });
+});
+
+app.listen(3000);
+```
+
+---
+
+## 3. Client Integration (Agent Paying for Access)
+
+If you are writing an AI Agent that needs to consume a paid x402 endpoint, do not handle the `402` retry logic manually. Use the client wrapper.
+
+The client wrapper automatically intercepts `402 Payment Required` responses, parses the cost, uses the Agent's private key to sign a transaction, and transparently retries the request with the `X-PAYMENT` header attached.
+
+```javascript
+import { wrapFetchWithPayment } from 'stellar-x402/client-http';
+import { Keypair } from '@stellar/stellar-sdk';
+
+// The agent's wallet
+const keypair = Keypair.fromSecret(process.env.STELLAR_SECRET_KEY);
+
+// Wrap the native fetch API
+const fetchWithPayment = wrapFetchWithPayment(fetch, keypair);
+
+async function getPremiumData() {
+  try {
+    // 1. Initial request (fails with 402)
+    // 2. Wrapper automatically signs payment
+    // 3. Wrapper automatically retries request with X-PAYMENT header
+    // 4. Returns the final 200 OK response
+    const response = await fetchWithPayment('https://api.example.com/premium-data');
+
+    const data = await response.json();
+    console.log(data); // { secret: "AI agents rule the world" }
+
+  } catch (error) {
+    console.error("Payment or network failed:", error);
+  }
+}
+```
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/x402 — MIT License*