stellarskills 1.0.0

package/fees/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: stellarskills-fees
+description: Stellar transaction fees, base fee, surge pricing, resource fees (Soroban), and fee bumps.
+---
+
+# STELLARSKILLS — Fees
+
+> Stellar transaction fees, base fee, surge pricing, resource fees (Soroban), and fee bumps.
+
+---
+
+## The Fee Philosophy
+
+Stellar is designed to be inexpensive. Fees exist primarily as a spam deterrent, not as a major source of revenue or yield for validators.
+
+On Stellar:
+- **Base Fee**: Applies to classic operations (payments, trustlines, etc.)
+- **Resource Fee**: Applies to Soroban smart contracts (CPU, memory, ledger I/O)
+- **Refunds**: You specify a maximum fee, but you are only charged the minimum necessary to be included in the ledger. The rest is refunded.
+
+---
+
+## Classic Fees (Base Fee)
+
+Every transaction specifies a `fee` (in **stroops**, where 1 XLM = 10,000,000 stroops). This is the **maximum total fee** you are willing to pay for the transaction.
+
+### Minimum Fee Calculation
+The minimum fee for a classic transaction is:
+```
+min_fee = base_fee × number_of_operations
+```
+
+- **Default base fee**: 100 stroops (0.00001 XLM)
+- Transaction with 1 operation: min fee = 100 stroops
+- Transaction with 10 operations: min fee = 1000 stroops
+
+```javascript
+import { TransactionBuilder, BASE_FEE } from "@stellar/stellar-sdk";
+
+// BASE_FEE constant is 100
+const tx = new TransactionBuilder(account, {
+  fee: BASE_FEE, // 100 stroops per operation
+  // ...
+});
+```
+
+### Surge Pricing (Fee Market)
+If the network is congested (more than 1000 operations per ledger), surge pricing activates. Transactions with higher base fees are prioritized.
+
+**Crucial detail**: You only pay the *lowest* fee required to make it into the ledger, up to your specified maximum. If you set your fee to 10,000 stroops, but the clearing price is 500 stroops, you only pay 500.
+
+### Dynamic Fee Estimation
+Always fetch current fee stats before building a transaction in production to avoid stalled transactions:
+
+```javascript
+const server = new Horizon.Server("https://horizon.stellar.org");
+const feeStats = await server.feeStats();
+
+// Use the 99th percentile for high priority, or 50th for normal
+const priorityFee = feeStats.fee_charged.p99;
+const normalFee = feeStats.fee_charged.p50;
+
+const tx = new TransactionBuilder(account, {
+  fee: priorityFee.toString(),
+  // ...
+});
+```
+
+---
+
+## Soroban Resource Fees
+
+Soroban smart contracts charge for the exact resources they consume:
+1. CPU instructions
+2. Memory (RAM)
+3. Ledger reads/writes (I/O)
+4. Transaction size (bytes)
+5. Events emitted
+
+### How to calculate
+You never calculate this manually. You must use `simulateTransaction` on the Soroban RPC.
+
+```javascript
+// 1. Build raw tx with a placeholder fee
+const tx = new TransactionBuilder(account, { fee: "100" })
+  .addOperation(contract.call("my_func"))
+  .build();
+
+// 2. Simulate
+const sim = await sorobanServer.simulateTransaction(tx);
+
+// 3. Assemble (applies footprint and calculated resource fee)
+const preparedTx = SorobanRpc.assembleTransaction(tx, sim);
+
+// preparedTx now has the correct fee and resources attached
+```
+
+### Extending Soroban Budgets
+If simulation fails because it hits the default resource limits, you can manually increase the budget (if the network max allows it):
+
+*(Note: Most dApps should optimize their contracts rather than increasing limits, as limits protect network throughput).*
+
+---
+
+## Fee Bump Transactions
+
+A fee bump transaction allows Account A to pay the fee for Account B's transaction *after* Account B has already signed it.
+
+**Use cases:**
+- Rescuing a stuck transaction (one submitted with too low a fee during a surge).
+- Sponsoring fees for users (dApp pays the gas so the user doesn't need XLM).
+
+### Creating a Fee Bump
+```javascript
+import { FeeBumpTransaction, TransactionBuilder, Networks } from "@stellar/stellar-sdk";
+
+// 1. You receive an inner transaction signed by the user (it might be stuck)
+// const innerTx = ...
+
+// 2. Wrap it in a FeeBump
+const feeBump = TransactionBuilder.buildFeeBumpTransaction(
+  sponsorKeypair,          // Account paying the higher fee
+  "5000",                  // New max base fee per operation (in stroops)
+  innerTx,                 // The original signed transaction
+  Networks.MAINNET
+);
+
+// 3. Sponsor signs
+feeBump.sign(sponsorKeypair);
+
+// 4. Submit
+await server.submitTransaction(feeBump);
+```
+
+**Important**: The inner transaction's sequence number and signatures remain valid. Only the fee payer changes.
+
+---
+
+## Common Errors
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `tx_insufficient_fee` | The network is surging and your fee is too low | Fetch `feeStats` and submit with higher fee, or use Fee Bump |
+| `op_underfunded` | Account doesn't have enough XLM to cover fee + min balance | Add more XLM. Remember minimum balance requirements! |
+| Soroban simulation `wasm_vm_error` | Contract exceeded resource budget (often CPU) | Optimize contract logic or reduce storage reads/writes |
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/fees — MIT License*

package/frontend/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: stellarskills-frontend
+description: Connecting web apps to Stellar. Stellar Wallets Kit, Freighter API, signing Soroban transactions, and secure SEP-10 Web3 Auth.
+---
+
+# STELLARSKILLS — Frontend Integration
+
+> Connecting web apps to Stellar. Stellar Wallets Kit, Freighter API, signing Soroban transactions, and secure SEP-10 Web3 Auth.
+
+---
+
+## 1. Connecting Wallets (The Modern Standard)
+
+To build a professional dApp with high UX, you must support multiple wallets (Freighter, Albedo, xBull, Lobstr, and WalletConnect) simultaneously. **Do not write custom logic for each extension.**
+
+Instead, use **Stellar Wallets Kit** (`@creit.tech/stellar-wallets-kit`), the standard "RainbowKit equivalent" for Stellar.
+
+```bash
+npm install @creit.tech/stellar-wallets-kit
+```
+
+### Initializing the Kit & Showing the Modal
+
+```javascript
+import {
+  StellarWalletsKit,
+  WalletNetwork,
+  allowAllModules,
+  FREIGHTER_ID
+} from '@creit.tech/stellar-wallets-kit';
+
+// 1. Initialize the kit globally in your React Context or state manager
+const kit = new StellarWalletsKit({
+  network: WalletNetwork.TESTNET,
+  selectedWalletId: FREIGHTER_ID,
+  modules: allowAllModules(),
+});
+
+// 2. Open the beautiful native UI modal to let user choose their wallet
+await kit.openModal({
+  onWalletSelected: async (option) => {
+    kit.setWallet(option.id);
+    const publicKey = await kit.getPublicKey();
+    console.log(`Connected with ${option.name}: ${publicKey}`);
+  }
+});
+```
+
+---
+
+## 2. Signing Transactions (Wallets Kit)
+
+Once connected, you can sign XDR transactions agnostically. The kit handles the extension pop-up whether the user is on Freighter or Albedo.
+
+```javascript
+import { TransactionBuilder, Networks, BASE_FEE, Operation } from "@stellar/stellar-sdk";
+
+// 1. Build the transaction (Requires fetching account sequence from Horizon)
+const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: Networks.TESTNET })
+  .addOperation(Operation.payment({ destination: "GBB...", asset: Asset.native(), amount: "10" }))
+  .setTimeout(30)
+  .build();
+
+// 2. Sign via Wallets Kit
+const { signedXDR } = await kit.signTx({
+  xdr: tx.toXDR(),
+  publicKeys: [userPublicKey],
+  network: WalletNetwork.TESTNET
+});
+
+// 3. Reconstruct and submit to Horizon/RPC
+const signedTx = TransactionBuilder.fromXDR(signedXDR, Networks.TESTNET);
+await horizonServer.submitTransaction(signedTx);
+```
+
+---
+
+## 3. Low-Level Integration: Freighter API
+
+If you absolutely must build a low-level, Freighter-only integration without UI wrappers, use `@stellar/freighter-api`.
+
+```bash
+npm install @stellar/freighter-api
+```
+
+```javascript
+import { isConnected, requestAccess, signTransaction } from "@stellar/freighter-api";
+
+// Connect
+if (await isConnected()) {
+  const address = await requestAccess();
+}
+
+// Sign
+const signedTxXdr = await signTransaction(tx.toXDR(), { network: "TESTNET" });
+```
+
+---
+
+## 4. Signing Transactions (Soroban Smart Contracts)
+
+When calling a Soroban smart contract, you cannot simply sign the operation. You must **simulate** the transaction first to fetch the correct resource footprint and fee, assemble it, and *then* request the user's signature.
+
+```javascript
+import { TransactionBuilder, Networks, BASE_FEE, Contract } from "@stellar/stellar-sdk";
+import { SorobanRpc } from "@stellar/stellar-sdk";
+
+const contract = new Contract(contractId);
+
+// 1. Build initial tx with default limits
+let tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: Networks.TESTNET })
+  .addOperation(contract.call("deposit", ...))
+  .setTimeout(30)
+  .build();
+
+// 2. Simulate via RPC to calculate the exact footprint and CPU fee
+const sim = await rpcServer.simulateTransaction(tx);
+if (SorobanRpc.Api.isSimulationError(sim)) throw sim.error;
+
+// 3. Assemble transaction with the correct simulated footprint
+tx = SorobanRpc.assembleTransaction(tx, sim);
+
+// 4. Request user signature via Wallets Kit or Freighter API
+const { signedXDR } = await kit.signTx({ xdr: tx.toXDR(), publicKeys: [userPublicKey] });
+
+// 5. Submit to RPC and poll
+const signedTx = TransactionBuilder.fromXDR(signedXDR, Networks.TESTNET);
+const sendResponse = await rpcServer.sendTransaction(signedTx);
+```
+
+---
+
+## 5. SEP-10 Web3 Auth (Security Warning)
+
+If your app has a backend and needs to securely authenticate the user via Web3, implement the **SEP-10** standard.
+
+### ⚠️ SECURITY RULE: Never store JWTs in LocalStorage
+Do not store the returned `auth_token` in `localStorage` or `sessionStorage`. This makes your frontend highly vulnerable to XSS (Cross-Site Scripting) attacks. The backend must set the JWT inside an `HttpOnly`, `Secure`, and `SameSite=Strict` (or `Lax`) cookie. Ensure all `fetch` calls to your protected API include `credentials: "include"`.
+
+### Frontend Implementation
+```javascript
+// 1. Fetch SEP-10 challenge from your backend
+const challengeResponse = await fetch("/api/auth/challenge?account=" + userPublicKey);
+const { transaction, network_passphrase } = await challengeResponse.json();
+
+// 2. Request user to sign the challenge transaction via wallet
+const { signedXDR } = await kit.signTx({
+  xdr: transaction,
+  publicKeys: [userPublicKey],
+  network: WalletNetwork.TESTNET
+});
+
+// 3. Send signed challenge back to backend
+// The backend verifies the signature. It MUST NOT return the token in the JSON body.
+// Instead, the backend sets the HttpOnly cookie in the response headers.
+await fetch("/api/auth/token", {
+  method: "POST",
+  body: JSON.stringify({ transaction: signedXDR }),
+  headers: { "Content-Type": "application/json" }
+});
+
+// 4. Subsequent authenticated requests
+// The browser will automatically attach the HttpOnly cookie
+const userProfile = await fetch("/api/me", { credentials: "include" });
+```
+
+---
+
+*raw.githubusercontent.com/ggoldani/stellarskills/main/frontend — MIT License*