DEV Community: Lymah

Transfer Fees, Metadata, and Soulbound Tokens: A Tour of Solana Token Extensions

Lymah — Sun, 24 May 2026 23:02:29 +0000

I spent the past week building tokens on Solana. Not wrapping existing ones, not swapping — actually creating token mints from scratch, attaching economic rules to them at the protocol level, and watching a blockchain reject a transaction I told it to make. This post walks through what I built, what surprised me, and why the Token Extensions Program changes how I think about on-chain rules.

Where I Started

My background is Web2. I know how platforms build internal currencies — a database table for balances, API endpoints for transfers, middleware to collect fees, application logic to enforce rules like "this badge can't be sold." It works, but the rules live in code that can be changed, bypassed, or taken offline.

My starting question going into this was simple: what does Solana actually give you that a well-designed backend doesn't? By the end of the week, I had a concrete answer.

1: Your First Mint (It's Just an Account)

The first thing that reframes everything is understanding that a token on Solana is not a smart contract. It's an account — specifically a Mint account — that stores three pieces of state: total supply, decimal precision, and the address that's allowed to create more tokens (the mint authority).

spl-token create-token
spl-token create-account YOUR_MINT_ADDRESS
spl-token mint YOUR_MINT_ADDRESS 100

What surprised me: you can't receive tokens directly into your wallet. Every wallet needs a dedicated token account for each token type it holds. Think of your wallet as a filing cabinet — each token account is a labeled folder inside it. It felt awkward at first, but it's how Solana keeps account state fast and cheap to look up.

The Mint account is the source of truth. The token account is where your specific balance lives. One program, the SPL Token Program, manages both.

2: Metadata — Giving Your Token an Identity

A freshly minted token has no name, no symbol, nothing. In a block explorer it shows up as "Unknown Token." That's where the Token Extensions Program (Token-2022) comes in.

Instead of storing metadata in a separate account (the old Metaplex approach), Token-2022 lets you attach metadata directly to the mint account itself using the metadata extension.

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --enable-metadata \
  --decimals 6

spl-token initialize-metadata YOUR_MINT "100DaysCoin" "HUNDO" \
  "https://your-metadata-uri.json"

The result: a single mint account that holds the token's supply, decimal config, mint authority, and its name and symbol. Fewer accounts, fewer transactions, lower cost. After running this I could see 100DaysCoin (HUNDO) show up properly in the Solana Explorer on devnet.

Key insight: The URI in the metadata points to a JSON file with extended details (description, image, attributes). It's the same pattern as NFT metadata — one on-chain pointer to off-chain details.

3: Transfer Fees — Economics Without Middleware

This is where things got genuinely interesting. In Web2, collecting a percentage of every transaction means building middleware: intercept the transfer, calculate the fee, split the payment, handle edge cases. And it can be bypassed if someone finds a way around your API.

Token-2022 has a transfer fee extension that enforces collection at the program level. When you configure it on a mint, every transfer of that token automatically withholds a percentage in the recipient's account — locked there until the withdraw authority (you) sweeps it out.

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --transfer-fee-basis-points 200 \
  --transfer-fee-maximum-fee 5000000000000 \
  --decimals 9

I transferred 100 tokens at a 2% fee. The recipient received 98. Two tokens were withheld in their account, untouchable by them. Then I ran the withdraw:

spl-token withdraw-withheld-tokens YOUR_TOKEN_ACCOUNT RECIPIENT_TOKEN_ACCOUNT

Final balance: 902. The 2 tokens came home.

What tripped me up: The --transfer-fee-maximum-fee parameter is in base units, not whole tokens. With 9 decimals, 5000 base units = 0.000005 tokens — basically nothing. My first two runs had the fee capped at a fraction of a token because I forgot to scale it. The fix: multiply by 10 ** decimals.

const MAX_FEE = BigInt(5000 * 10 ** DECIMALS); // 5000 whole tokens as cap

This is the kind of thing that only clicks after you see the wrong number in your output.

4: The Full Lifecycle in One Run

Day 4 was a consolidation challenge: reproduce the entire workflow — metadata + transfer fees — from a blank terminal without notes. I built a single Node.js script that:

Created a Token-2022 mint with both metadata and transfer fee extensions
Minted 1000 tokens
Transferred 100 to a second wallet (98 received, 2 withheld)
Harvested and withdrew the fees
Printed the full token config as a summary

```Final output:

Primary wallet: 902 tokens
Second wallet: 98 tokens


Fees collected:    2 tokens

Running it clean, without errors, in one go, felt like the proof that the concepts had actually landed.

---

## Day 5: Non-Transferable Tokens — Soulbound on the Protocol

The last experiment was the most conceptually interesting. Solana's Token-2022 has a **non-transferable extension** that permanently prevents any token from that mint from moving between wallets. Not "our API won't let you" — the transaction is rejected by the token program before it even hits the chain.



```bash
spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --enable-non-transferable

I minted 10 tokens, tried to transfer 5 to a second wallet, and got this:

✗ TRANSFER REJECTED (This is correct!)
Error: Transaction simulation failed: Error processing instruction
The Non-Transferable extension blocks ALL transfers at the protocol level.

Then I burned 3 tokens — and that worked fine. Balance dropped from 10 to 7.

That distinction matters: non-transferable doesn't mean non-destructible. The holder can burn their own tokens. They just can't send them to anyone else. This is exactly the behavior you'd want for things like:

Course completion certificates
KYC verification tokens
DAO membership credentials
Event participation proofs

In Web2, preventing credential trading means application-layer rules. Here, the restriction is part of the asset itself. No backend change, no API update, no workaround possible.

What I'd Tell Myself at the Start

1. Read the error messages carefully. Solana program errors are specific. "NonTransferable" in an error isn't noise — it's the program telling you exactly which extension blocked you.

2. Base units will get you. Every numeric parameter involving token amounts is in base units. Always multiply by 10 ** decimals before passing values into instructions.

3. Extensions are set at creation time. You can't add a transfer fee to an existing mint. Design your token before you deploy it.

4. Token-2022 is the right default now. The original SPL Token Program is simpler, but Token-2022 is a strict superset. Unless you have a specific reason to use the old program, start with Token-2022.

What's Next

I'm continuing through the 100 Days of Solana challenge. Next up: diving into compressed NFTs and Solana's state compression model. If you're following along or building something similar, drop a comment — I'd like to see what you're working on.

Built on Solana devnet. All code written in Node.js using @solana/web3.js and @solana/spl-token. Windows environment — no CLI available, so every challenge was solved programmatically.

Solana's System Program: Understanding the Kernel

Lymah — Fri, 22 May 2026 06:08:17 +0000

The Question That Started It All

Three posts in, I kept running into the same address:
11111111111111111111111111111111.

It showed up as the owner of every wallet I queried.
It appeared in every transaction I decoded in
Post 3.
My explorer from Post 2
labeled it "System Program" but I didn't really
understand what that meant.

Why can't I create an account myself? Why does the
System Program have to do it? Why does every wallet
on Solana belong to it?

The answer reveals Solana's elegance: The System
Program is Solana's kernel. Like a Unix kernel
manages processes and permissions, the System Program
manages accounts and state creation. Understanding it
means understanding why Solana works the way it does.

What is the System Program?

Address: 11111111111111111111111111111111

It's an account like any other:

Owner: NativeLoader
Executable: true
Data: "system_program" (14 bytes of ASCII)
Balance: 1 lamport (rent-exempt minimum)

But it's special. It's built into Solana's validator
runtime. When you send a transaction, the System
Program enforces:

Who can transfer SOL
Who can create accounts
How much lamports accounts must hold
Account closure rules

Run this yourself and see:

solana account 11111111111111111111111111111111

The System Program — owned by NativeLoader, built
into the validator runtime itself.

Core Insight: Programs Own Accounts, Not People

Here's what breaks beginner brains:

Your wallet is NOT owned by you. It's owned by the
System Program.

Your Wallet
├── Owner: 11111111111111111111111111111111 (System Program)
├── Executable: false
├── Data: (empty)
└── Lamports: 5000000000 (your SOL)
Run this to see it yourself:

solana account <your-wallet-address>

Your wallet — owned by the System Program, not by
you. Your keypair is the authorization mechanism,
not the owner.

But you can spend from it because:

Your keypair can sign for this account
The System Program's rules say: "Only an account owner or authorized keypair can transfer from that account"
Since your keypair authorized the transfer, the System Program allows it

You don't own your account. You authorize
transactions on it. The System Program enforces
your authorization.

This is the security model: permission enforcement
is separate from asset ownership.

The System Program's Four Main Instructions

1. CreateAccount

Creates a new account owned by you or another program.

// What it does:
// 1. Allocate <space> bytes for data
// 2. Set owner to <owner> (usually your program)
// 3. Charge enough lamports to cover rent
// 4. Fund from payer's account

Cost: ~2,400 lamports for a basic account +
space × 0.00348 lamports/byte

2. Transfer

Move SOL from one account to another.

// What it does:
// 1. Decrease sender's lamports by amount
// 2. Increase recipient's lamports by amount
// 3. Verify sender's keypair signature

No fee beyond the network fee. The System Program
allows SOL transfer to any account.

3. Allocate

Increase an account's data space after creation.

// What it does:
// 1. Expand data buffer
// 2. Charge additional lamports for rent

4. Assign

Change an account's owner.

// What it does:
// 1. Set owner to <new-owner>
// 2. Only works if current owner is System Program

Example: The Lifecycle of Creating an Account

When you create a token, the Token Program does this:
User sends transaction:
│
├─> System Program.CreateAccount(...)
│ ├─ Payer: Your wallet
│ ├─ New Account: Token mint address
│ ├─ Owner: Token Program
│ └─ Space: 82 bytes
│
└─> Token Program.InitializeMint(...)
├─ Reads the new account
├─ Writes mint data
└─ Returns success
Result:
Token Mint Account
├── Owner: TokenkegQfe... (Token Program)
├── Executable: false
├── Data: (82 bytes with supply, decimals, authorities)
└── Lamports: (rent-exempt amount)
Notice the two-step pattern:

System Program creates the container — allocates space, funds rent
Token Program initializes the data — writes the mint info

This separation is the genius: the System Program
handles account creation, programs handle
initialization.

Rent: The System Program's Economic Rule

The System Program enforces rent-exemption economics.

You must hold:
(account_data_size + 128) × 0.00348 lamports/byte

// Example: 1 KB account
const dataSize = 1000;
const rentPerByte = 0.00348; // lamports
const requiredLamports = (dataSize + 128) * rentPerByte;
const requiredSOL = requiredLamports / 1e9;

console.log(`Required: ${requiredSOL} SOL`);

Check it yourself:

solana rent 1000

The exact SOL required to rent-exempt a 1KB
account. The System Program enforces this minimum
at account creation.

Note: Only 0.000000004 SOL for 1KB — rent-exemption
is cheap for small accounts. Scale this up to
10MB and it becomes meaningful.

Note on rent deprecation: Solana deprecated
ongoing rent collection, but the rent-exemption
minimum is still enforced when accounts are created.
You must fund new accounts above this threshold or
the transaction fails.

Seeing It Through the Explorer

If you built the account explorer from
Post 2,
run it against the System Program now:

node explorer.mjs 11111111111111111111111111111111

The same explorer from Post 2 — but now you know
exactly what you're looking at. NativeLoader means
this program is baked into the validator, not deployed
like other programs.

The output tells the whole story in five fields.

Why This Design?

Consistency

Every program uses the same account model. Every
account creation uses the System Program. The
protocol scales because you don't write custom
account-creation logic.

Security

The System Program is battle-tested and immutable.
Bugs there would be catastrophic. By centralizing
account logic, Solana minimizes the surface area
for vulnerabilities.

Economics

Rent exemption is managed uniformly. Everyone follows
the same rules: hold enough lamports and your account
lives forever.

Auditability

Want to know who owns an account? Read the owner
field. Solana's permission model is transparent and
on-chain.

System Program vs. Ethereum

Ethereum:

Anyone can create accounts implicitly
Storage rent is implicit through gas fees
Account ownership is straightforward

Solana:

System Program explicitly creates all accounts
Rent-exemption is explicit — you must hold a minimum balance
Account ownership is decoupled from transaction authorization — owner vs. signer are different things

Solana's model is more explicit. You see the kernel.
You can audit it. That explicitness is a feature,
not a bug.

Debugging: Common System Program Errors

"Account does not have enough lamports."

❌ You tried to create an account without funding
it enough
✅ Calculate the rent-exempt amount and include
extra lamports

"Account is not owned by the System Program"

❌ You tried to Assign an account owned by a
different program
✅ Only the System Program can Assign accounts

"Cannot allocate more space"

❌ Account is owned by something other than the
System Program
✅ Only the System Program allows re-allocation

What to Do Next

Inspect the System Program

   solana account 11111111111111111111111111111111

Check your own wallet's owner

   solana account <your-address>

Owner will always be 11111... for a standard wallet.

Check rent for different sizes

   solana rent 1000    # 1 KB
   solana rent 10000   # 10 KB
   solana rent 100000  # 100 KB

Watch how the required SOL scales with data size.

Read the System Program source The code is public. Reading it shows you the exact validation rules the entire network runs on.

Wrapping Up Epoch 1

This is the fourth and final post in my Epoch 1
Writing Challenge series. What started with
"everything is an account" ends here — with the one
program that makes the whole account model work.

If you've followed along from Post 1, you now have
a complete mental model:

Post 1 — What accounts are and why they all share five fields
Post 2 — How to query any account and read those fields directly
Post 3 — How to decode the raw binary data sitting in those fields
Post 4 — The System Program that creates, owns, and enforces rules on all of it

That's Solana's foundation. Everything else — DeFi,
NFTs, DAOs, gaming — is built on top of this.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer
Part 3: Decoding Account Data
Part 4: Solana's System Program — Understanding the Kernel (this post)

Have questions about the System Program? Ask in
the comments — I'll cover advanced patterns like
PDAs (Program Derived Addresses) in a future post.

Part of the 100 Days of Solana Epoch 1 Writing Challenge.

Decoding Solana Account Data: Three Methods Compared

Lymah — Wed, 20 May 2026 17:09:25 +0000

From Hex to Human-Readable

At the end of Post 2, my account explorer was printing this for the Token Program:

Data:
Size: 48 bytes
First 48 bytes (hex):
7436346a506...

I could see the data existed. I had no idea what it meant.

That wall of hex bytes is actually structured information — token supply, decimals, mint authority. It's just encoded in binary. This post is about the three ways I learned to decode it, what each method taught me, and when to use which.

The Problem

You've got an account. You can fetch it. But the data field is a binary blob:

data: [2, 0, 0, 0, 39, 241, 144, 177, 211, 175, 152, 184, 206, 113, 76, 68, ...]

How do you turn this into meaningful information?

This is where decoding comes in. And it turns out, there are three different ways to do it in Solana. Each has tradeoffs.

Background: Account Data is Binary Borsh

SPL (Solana Program Library) accounts use Borsh, a binary serialization format. It's deterministic, language-independent, and compact.

For example, a token mint account is 82 bytes:

Bytes 0-3:       Mint discriminator
Bytes 4-35:      Mint authority (32-byte public key)
Bytes 36-43:     Total supply (u64 = 8 bytes, little-endian)
Byte 44:         Number of decimals (u8)
Bytes 45-76:     Freeze authority (32-byte public key)

Raw bytes look like nonsense. Decoding means:

Reading bytes at specific offsets
Interpreting them as specific types
Converting little-endian → numbers

We need a reliable way to do this.

Method 1: Using a Codec Library

The cleanest approach: use @solana-program/token with its built-in decoders.

npm install @solana-program/token

import { getMintDecoder } from "@solana-program/token";
import { base58Decoder } from "@solana/codecs";

async function decodeWithCodec() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");

  // Fetch the token mint
  const WRAPPED_SOL = "So11111111111111111111111111111111111111112";
  const accountInfo = await connection.getAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  // Decode using the official codec
  const mintDecoder = getMintDecoder();
  const decodedMint = await mintDecoder.decode(accountInfo.data);

  console.log("Method 1: Codec");
  console.log("Supply:", decodedMint.supply);
  console.log("Decimals:", decodedMint.decimals);
  console.log("Mint Authority:", decodedMint.mintAuthority);
  console.log("Freeze Authority:", decodedMint.freezeAuthority);
}

Pros:

✅ Type-safe
✅ Official/audited
✅ Handles complex types automatically
✅ No manual offset calculations

Cons:

❌ Only works for SPL types
❌ External dependency
❌ Black box — you don't see the binary

Method 2: Manual Byte-Level Parsing

Read raw bytes and extract fields yourself using DataView.

function decodeManually(data) {
  const view = new DataView(data.buffer);

  // Bytes 0-3: Skip discriminator

  // Bytes 4-35: Mint authority (public key = 32 bytes, stored as base58)
  const mintAuthBytes = data.slice(4, 36);

  // Bytes 36-43: Supply (u64, little-endian)
  const supply = view.getBigUint64(36, true);

  // Byte 44: Decimals (u8)
  const decimals = view.getUint8(44);

  // Bytes 45-76: Freeze authority
  const freezeAuthBytes = data.slice(45, 77);

  return {
    mintAuthority: base58Decoder.encode(mintAuthBytes),
    supply,
    decimals,
    freezeAuthority: base58Decoder.encode(freezeAuthBytes)
  };
}

Key gotcha: The true parameter means little-endian. Solana uses little-endian (LSB first). Get this wrong and your numbers are garbage.

// ❌ WRONG - big-endian
const supply = view.getBigUint64(36, false);  // Incorrect!

// ✅ CORRECT - little-endian
const supply = view.getBigUint64(36, true);   // Correct

Pros:

✅ Complete control
✅ Learn exactly how serialization works
✅ Works for any binary format
✅ No dependencies

Cons:

❌ Easy to get offsets wrong
❌ Tedious for complex structures
❌ No type checking
❌ Must handle endianness manually

Method 3: RPC's jsonParsed Format

Let Solana's RPC do the parsing for you:

async function decodeViaRpc() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");

  const WRAPPED_SOL = "So11111111111111111111111111111111111111112";

  // Use getParsedAccountInfo instead of getAccountInfo
  const accountInfo = await connection.getParsedAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  const parsed = accountInfo.value.data.parsed.info;

  console.log("Method 3: RPC jsonParsed");
  console.log("Supply:", parsed.supply);
  console.log("Decimals:", parsed.decimals);
  console.log("Mint Authority:", parsed.owner);
}

Pros:

✅ One RPC call
✅ Automatic parsing
✅ Type-safe JSON response
✅ Easiest to implement

Cons:

❌ Only works for known program types
❌ Depends on RPC node supporting it
❌ Can't inspect raw data
❌ Slower than local parsing

Comparison: Real Results

I tested all three methods on Wrapped SOL (So11111111...):

Method 1 (Codec):      Supply: 10234567890000000000n, Decimals: 9
Method 2 (Manual):     Supply: 10234567890000000000n, Decimals: 9
Method 3 (RPC):        Supply: "10234567890000000000", Decimals: 9

Status: ✅ All three match!

Deciding Which to Use

Use Method 1 (Codec) if:

You're working with SPL types (tokens, mints, associated accounts)
You want type safety
You're okay with an external dependency

Use Method 2 (Manual) if:

You're parsing custom program data
You want to understand the binary format
You need maximum control
You're building low-level tools

Use Method 3 (RPC) if:

You're building quick scripts
The RPC node supports parsing your account type
Performance isn't critical
You just want the data, not the details

Real-World Example: Parsing Token Account Data

Here's where it gets practical. A token account has a different structure than a mint. Let's decode one:

async function decodeTokenAccount(address) {
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const accountInfo = await connection.getAccountInfo(new PublicKey(address));

  const view = new DataView(accountInfo.data.buffer);

  // Token account structure:
  // 0-31:   Mint (32 bytes)
  // 32-63:  Owner (32 bytes)
  // 64-71:  Amount (u64)
  // 72:     Decimals (u8)
  // 73-103: Delegate (32 bytes)
  // etc.

  const amount = view.getBigUint64(64, true);
  const decimals = view.getUint8(72);
  const realAmount = Number(amount) / Math.pow(10, decimals);

  console.log(`Token Balance: ${realAmount}`);
}

The Key Insight

Borsh serialization is deterministic: given the same account data, all three methods produce identical results. The difference is:

Implementation complexity (codec > RPC > manual)
Type safety (codec > manual > RPC)
Performance (manual > codec > RPC)
Flexibility (manual > codec > RPC)

Choose based on your use case.

Practical Debugging

When parsing fails, debug systematically:

console.log("Raw data length:", data.length);
console.log("First 10 bytes:", data.slice(0, 10));

const view = new DataView(data.buffer);
for (let i = 0; i < Math.min(64, data.length); i += 8) {
  const value = view.getBigUint64(i, true);
  console.log(`Offset ${i}: ${value} (0x${value.toString(16)})`);
}

Often the issue is:

Wrong offset (miscounted bytes)
Wrong endianness (used false instead of true)
Wrong data type (u32 instead of u64)
Missing discriminators or padding

Check the SPL source code for the exact account layout.

The Full Example

Here's a complete script using all three methods:

import { Connection, PublicKey } from "@solana/web3.js";
import { getMintDecoder } from "@solana-program/token";
import { base58Decoder } from "@solana/codecs";

const WRAPPED_SOL = "So11111111111111111111111111111111111111112";

async function compareDecodingMethods() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const accountInfo = await connection.getAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  // Method 1: Codec
  const mintDecoder = getMintDecoder();
  const m1 = await mintDecoder.decode(accountInfo.data);

  // Method 2: Manual
  const view = new DataView(accountInfo.data.buffer);
  const m2 = {
    supply: view.getBigUint64(36, true),
    decimals: view.getUint8(44)
  };

  // Method 3: RPC
  const parsed = await connection.getParsedAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );
  const m3 = parsed.value.data.parsed.info;

  console.log("Supply Comparison:");
  console.log("Codec:", m1.supply);
  console.log("Manual:", m2.supply);
  console.log("RPC:", m3.supply);
}

compareDecodingMethods();

Challenge

Try parsing a token account you own:

Get the account address
Fetch it via RPC
Decode using all three methods
Verify they match

Understanding this deepens your grasp of Solana's data model.

Next in this series: Post 4 covers Solana's System Program — the kernel-level program that owns every wallet and enforces the rules that hold the whole network together.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer
Part 3: Decoding Account Data (this post)
Part 4: System Program Deep Dive (coming May 22)

Which method do you prefer? Let me know in the comments!

Part of the 100 Days of Solana Epoch 1 Writing Challenge.

Building a Solana Account Explorer: Query On-Chain Data Like a Database

Lymah — Mon, 18 May 2026 17:58:44 +0000

From Concept to Code

In Part 1 of this series, I explained that everything on Solana is an account with five fields: lamports, data, owner, executable, and rent_epoch.

That's the theory. But theory only sticks when you run it against real data.

So I built a command-line account explorer that queries any Solana address and prints all five fields in a readable format. In this post, I'll walk you through how I built it, what I learned from the output, and the three things that genuinely surprised me when I started querying real accounts.

By the end, you'll have a tool you can run against any address on the network — and a much sharper intuition for what's actually living on-chain.

What We're Building

A CLI tool that takes any Solana address and returns:

Balance in both SOL and lamports
Owner program (with friendly names for known programs)
Whether it's executable or a data account
Data size and a hex preview of the first bytes
Rent epoch

Here's what the output looks like against three different account types:

A wallet account:

The Token Program:

The System Program itself:

Same five fields. Three completely different accounts. Let's build it.

Setup

mkdir solana-account-explorer
cd solana-account-explorer
npm init -y
npm install @solana/kit

Create explorer.mjs — we use .mjs for ES module syntax with top-level await.

The Full Code

import { createSolanaRpc } from "@solana/kit";

// Known program addresses mapped to friendly names
const KNOWN_PROGRAMS = {
  "11111111111111111111111111111111": "System Program",
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA": "Token Program",
  "TokenzQdsByhw9vBi3wq3kQtj78oYCa9PzPgcGW8K3": "Token Program (SPL-2022)",
  "ATokenGPvbdGVqstVQmcLsNZAqeEoctVrGMMXuLYDJ": "Associated Token Program",
  "9xQeWvG816bUx9EPjHmaT23yfBYP5ihLeLSKcsFqrXa": "Raydium Program",
  "JUP4Fb2cqiRUcaTHdrPC8h2gNsszFildan3xnjnZALn": "Jupiter Aggregator",
  "DezXAZ8z7PnrnRJjz3wXBoRgixVpdZuvXAfqJ7DKPs1": "Magic Eden",
  "BPFLoaderUpgradeab1e11111111111111111111111": "BPF Loader (Program Upgrades)",
  "BPFLoader2111111111111111111111111111111111": "BPF Loader",
};

// Get address from command line argument
const address = process.argv[2];

if (!address) {
  console.error("❌ Error: No address provided!");
  console.error("Usage: node explorer.mjs <solana-address>");
  process.exit(1);
}

// Connect to devnet
const rpc = createSolanaRpc("https://api.devnet.solana.com");

async function exploreAccount() {
  try {
    console.log("\n🔍 Solana Account Explorer\n");
    console.log("━".repeat(60));

    // Fetch balance and account info in parallel
    const [balance, accountInfo] = await Promise.all([
      rpc.getBalance(address).send(),
      rpc.getAccountInfo(address).send(),
    ]);

    // Convert lamports to SOL
    const solBalance = (Number(balance.value) / 1e9).toFixed(9);
    console.log(`\n📍 Address:\n   ${address}\n`);
    console.log(`💰 Balance:\n   ${solBalance} SOL (${balance.value} lamports)\n`);

    if (!accountInfo.value) {
      console.log("ℹ️  This address does not exist on the blockchain yet.\n");
      console.log("━".repeat(60) + "\n");
      return;
    }

    // Resolve owner to friendly name if known
    const owner = accountInfo.value.owner;
    const ownerName = KNOWN_PROGRAMS[owner] || owner;
    console.log(`👤 Owner:\n   ${ownerName}\n`);

    // Executable flag
    const isExecutable = accountInfo.value.executable;
    console.log(
      `⚙️  Executable:\n   ${isExecutable ? "Yes (Program Account)" : "No (Data/Wallet Account)"}\n`
    );

    // Rent epoch
    console.log(`📅 Rent Epoch:\n   ${accountInfo.value.rentEpoch}\n`);

    // Data size and hex preview
    const dataLength = accountInfo.value.data.length;
    console.log(`📦 Data:\n   Size: ${dataLength} bytes\n`);

    if (dataLength > 0) {
      const displaySize = Math.min(64, dataLength);
      const dataSample = Buffer.from(accountInfo.value.data)
        .slice(0, displaySize)
        .toString("hex");
      console.log(`   First ${displaySize} bytes (hex):`);
      console.log(`   ${dataSample}`);
      if (dataLength > displaySize) {
        console.log(`   ... (${dataLength - displaySize} more bytes omitted)`);
      }
    } else {
      console.log(`   (empty)\n`);
    }

    console.log("\n" + "━".repeat(60) + "\n");
  } catch (error) {
    console.error("❌ Error exploring account:");
    console.error(error.message);
    process.exit(1);
  }
}

exploreAccount();

Run it against any address:

# Query the System Program
node explorer.mjs 11111111111111111111111111111111

# Query the Token Program
node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA

# Query your own wallet
node explorer.mjs <your-wallet-address>

What the Output Taught Me

The System Program owns itself — sort of

When I queried 11111111111111111111111111111111, I expected to see the System Program as its own owner. Instead I got NativeLoader.

That threw me until I understood: NativeLoader is the Solana runtime's built-in loader. It owns the System Program the same way a kernel owns its own system calls. The System Program is baked into the runtime at a level below the normal account ownership model. It's not a program that was deployed — it was compiled into the validator itself.

Key difference from Token Program: The Token Program is owned by BPF Loader (Program Upgrades), which means it was deployed like any other program and can be upgraded. The System Program cannot — it's part of the protocol.

The Token Program is only 48 bytes — but controls everything

Look at the Token Program output: 48 bytes of data. That's it. 48 bytes of what turns out to be a pointer — not the actual bytecode.

This is because the Token Program uses the upgradeable BPF loader pattern. The 48 bytes in the main account point to a separate program data account that holds the actual bytecode. The split exists so the program can be upgraded without changing its address.

This was my first real encounter with indirection on Solana — the account you call isn't always where the code lives.

A wallet with 0 bytes of data is a complete account

The wallet output shows Size: 0 bytes and (empty) for data. In Web2 terms that looks like a broken record — a row with no content. But on Solana, a wallet doesn't need data. Its entire purpose is to hold lamports. The owner field (System Program) and the lamports field are all it needs to function.

This is the account model in action: the structure is always the same, but some fields are intentionally empty depending on the account's purpose.

Three Things Worth Noticing in Your Own Queries

1. Compare executable accounts vs data accounts

Run the explorer on a program address and a wallet address back to back. Notice how executable: Yes vs executable: No changes everything about what that account does — even though both have identical field structures.

2. Watch the owner field

Every account you'll ever encounter is owned by exactly one program. Query five random addresses and look at what owns them. You'll start recognizing patterns: wallets owned by System Program, tokens owned by Token Program, NFT metadata owned by Metaplex's program.

3. The data field is where all the interesting stuff hides

The hex bytes in the data field aren't random — they're structured binary data that each program knows how to decode. That wall of hex is actually a token supply, or a price oracle, or a governance vote. Decoding that raw data is exactly what Post 3 covers.

The `KNOWN_PROGRAMS` Map — Why It Matters

One design choice worth explaining: the KNOWN_PROGRAMS lookup table at the top of the file.

Without it, the owner field just shows a raw base58 address like BPFLoaderUpgradeab1e11111111111111111111111. With it, you see BPF Loader (Program Upgrades) — immediately meaningful.

This is the same pattern Solana Explorer uses under the hood. As you build on Solana, you'll develop your own mental map of which program addresses do what. This table is a starter version of that map. Add to it as you encounter new programs.

Try It Yourself

# Copy the code above into explorer.mjs, then:
npm install @solana/kit

# Try these three to see the contrast clearly:
node explorer.mjs 11111111111111111111111111111111
node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
node explorer.mjs SysvarC1ock11111111111111111111111111111111

Each one will show you the same five fields, completely different values. That contrast is worth seeing with your own eyes.

What's Next

This explorer shows you the raw bytes in the data field — but doesn't tell you what they mean. A token mint's data field contains supply, decimals, and mint authority. A governance account's data field contains vote counts and proposal state. All of it is encoded in binary.

Post 3 covers exactly that: three methods for decoding raw Solana account data, from manual buffer parsing to using Anchor's IDL to using pre-built deserializers. That's where the hex bytes stop being noise and start being information.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer (this post)
Part 3: Decoding Account Data (coming May 20)
Part 4: System Program Deep Dive (coming May 22)

What address did you query first? Drop it in the comments — I'd love to see what people are exploring.

Part of the 100 Days of Solana Epoch 1 Writing Challenge.

# Week 4: Understanding Solana’s Account Model as a Web2 Developer

Lymah — Sat, 16 May 2026 21:56:55 +0000

If you come from a Web2 background, Solana’s account model can feel confusing at first.

You might ask:

“Why does everything seem to be an account?”

In traditional backend development, your application state usually lives in a database like PostgreSQL or MongoDB. Your server controls the logic, updates records, and manages permissions.

On Solana, things work differently.

The Core Idea

On Solana, everything is stored inside accounts.

Think of an account as a structured container that holds:

Data
Tokens
Program state
Ownership information

Instead of a centralized server managing a database, Solana stores application state directly on-chain inside these accounts.

A Web2 Analogy

Here’s a simple comparison:

Web2	Solana
Database row	Account
Backend server	Program
API endpoint	Instruction
User session	Wallet
Database update	Transaction

If you have built a REST API before, you can think of a Solana program as your backend logic.

But unlike Web2 servers:

Programs are mostly stateless
State lives in accounts
Users sign transactions directly with wallets

Programs vs Accounts

This is one of the biggest mindset shifts.

Programs

Programs contain executable logic.

They are similar to backend services or server functions.

However, programs do not store mutable state internally.

Accounts

Accounts store the actual data.

For example:

User profile data
NFT metadata
Token balances
Game state

When a Solana program runs, it receives accounts as input, modifies them if allowed, then saves the updated state back on-chain.

Ownership Matters

Every Solana account has an owner.

The owner determines which program can modify the account’s data.

Example:

A token account is owned by the Solana Token Program
Your wallet may control the tokens
But only the token program can modify token balances

This creates strong security guarantees.

Rent and Storage

Unlike traditional databases, blockchain storage is expensive.

On Solana, accounts must hold enough SOL to remain active. This is called rent exemption.

You can think of it like prepaying for storage space.

The larger the account data, the more SOL required.

Why This Model Exists

Solana’s account model is designed for:

Parallel transaction execution
High throughput
Predictable state access

Because transactions specify which accounts they will read or write beforehand, Solana can process many transactions simultaneously.

This is one reason Solana achieves very high performance compared to many blockchains.

Example Mental Model

Imagine building a todo app.

In Web2:

Frontend sends request to backend
Backend updates database
Database stores todo item

In Solana:

Wallet signs transaction
Transaction calls a program
Program updates a todo account
Updated state is stored on-chain

The blockchain itself becomes the shared database.

Final Thoughts

The hardest part of learning Solana is not syntax — it is changing how you think about application state.

Once you understand that:

programs execute logic
accounts store state
wallets authorize actions

…the architecture starts making much more sense.

For Web2 developers, Solana development feels less like building a traditional backend and more like designing a distributed state machine.

And that mindset shift is the key to understanding blockchain development.

The Solana Account Model Explained: Everything is an Account

Lymah — Sat, 16 May 2026 21:31:20 +0000

The Aha Moment

During Epoch 1 of #100DaysOfSolana, I hit a wall. I'd built wallets, sent transactions, decoded data — but nothing clicked until I stopped thinking about Solana like traditional programming and started thinking about it as a system where everything is an account.

When I started learning Solana, I kept hearing this phrase: "everything is an account." It sounded like philosophy. But then it hit me: there are literally no users, no wallets, no programs in Solana — only accounts. Your wallet is an account. The Token Program is an account. The system clock is an account. Even your SOL balance is just data in an account.

This single concept unlocks everything else on Solana.

What Is an Account? The Five-Field Structure

Every account on Solana has exactly five fields:

{
  lamports: 5000000,           // Balance (1 SOL = 1 billion lamports)
  data: [0x00, 0x01, ...],     // Binary data (up to 10 MB)
  owner: "11111111111...",     // Program that can modify this account
  executable: false,            // Is this a program (true) or data (false)?
  rent_epoch: 18446744073709... // Rent exemption status
}

That's it. Five fields. Everything on Solana fits into this model.
This is a real account (System Program) showing all five fields. You'll see this exact structure for every account on Solana.

Understanding Each Field

lamports - The account's balance in the smallest unit. Accounts must hold enough SOL (lamports) to be "rent-exempt" (roughly $0.02-$2 depending on data size). This prevents network spam. I built a rent calculator and went deeper on storage costs in my Week 2 post if you want the full breakdown.

data - Where the actual information lives. For a wallet, this is empty (0 bytes). For a program, this is bytecode. For a token mint, this is token metadata (supply, decimals, authorities). For a sysvar, this is cluster state.

owner - The program that has permission to modify this account's data. Your wallet is owned by the System Program (11111111111...), so only the System Program can transfer your SOL. A token mint is owned by the Token Program, so only it can mint new tokens.

executable - A boolean flag. If true, this account contains program code and can execute instructions. If false, it's just a data account.

rent_epoch - A legacy field from when Solana charged rent monthly. Now mostly ignored, but technically tracks when rent was last collected.

Three Account Types: Wallets, Programs, and Sysvars

Let me show you how the same five-field structure represents completely different things:
Same five fields, three completely different meanings. This is the power of the account model.

Type 1: Your Wallet (A Data Account)

Owner:      11111111111111111111111111111111  ← System Program
Executable: false                              ← Stores data, not code
Data:       (empty, 0 bytes)
Lamports:   5000000000                         ← Your SOL balance
Rent Epoch: 18446744073709551615 (max)         ← Rent exempt

This is what your wallet looks like on-chain: owned by System Program, no data, just lamports.

Your wallet is a System Program-owned account with empty data. The "balance" is just the lamports field. That's it.

Key insight: You don't own your wallet — the System Program does. The System Program enforces the rules that only the private key owner can transfer SOL. Your keypair is the authorization mechanism, not the owner — if this distinction feels fuzzy, I covered how Solana identity and keypairs actually work in my Week 1 post. This is what "custody" means on Solana: the program is the enforcer.

Type 2: The Token Program (An Executable Account)

Owner:      BPFLoaderUpgradeab1e...          ← BPF Loader (manages programs)
Executable: true                              ← Contains program code
Data:       (36 bytes of bytecode)            ← The actual program logic
Lamports:   ~11 SOL                           ← Program's retained SOL
Rent Epoch: 18446744073709551615              ← Rent exempt

Address: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
👆 Notice: executable=true, balance is 11+ SOL, owned by BPF Loader. This is a program account.

The Token Program is an executable account. Its data field contains the program bytecode that defines how tokens work. When you interact with a token (mint, transfer, burn), you're actually calling instructions in this program.

Key insight: Programs are just data stored in accounts. The Solana runtime reads the executable: true flag and knows to execute that account's code. This is why upgrading programs is so clean on Solana — you're just swapping the data in an account.

Type 3: Clock Sysvar (A System Data Account)

Owner: Sysvar1111111111111... ← Sysvar program
Executable: false ← Stores data, not code
Data: (40 bytes of binary time data) ← Current slot, epoch, timestamp
Lamports: ~1 SOL ← Enough for rent exemption
Rent Epoch: 18446744073709551615 ← Rent exempt
Address: SysvarC1ock11111111111111111111111111111111

This sysvar is readable by every program but not executable. It contains cluster time state.

Why This Matters: Three Real-World Scenarios

The Clock sysvar is a read-only data account containing cluster-wide state. Every program can read the current slot, epoch, and Unix timestamp from this account. It's like /proc/uptime in Linux — a public system file anyone can read.

Key insight: Sysvars are how programs access external state without making RPC calls. The Solana runtime updates them every slot.

Scenario 1: Sending SOL to a Friend

When you send 1 SOL to a friend:

Your wallet account (owned by System Program) loses 1 billion lamports
Your friend's account gains 1 billion lamports
The System Program enforces that only your keypair can authorize this

Both accounts follow the same five-field structure. The only difference is the keypair that can sign for them.

Scenario 2: Creating a Token

When someone creates a USDC token:

They invoke the Token Program (an executable account)
The Token Program creates a new account for the token mint
That new account has the Token Program as its owner
The Token Program stores token metadata in the mint account's data field

Same five-field structure. Different owner (Token Program instead of System Program).

Scenario 3: Reading the Network Time

Inside a program, you might read the current slot:

const clockSysvar = await connection.getAccountInfo(CLOCK_ADDRESS);
const decodedClock = parseClockData(clockSysvar.data);
console.log(`Current slot: ${decodedClock.slot}`);

You're just reading the data field of an account. Solana's runtime automatically updates that account every slot.

The Permission Model: Who Can Modify What?

Here's the crucial rule: Only the account's owner program can modify its data.

If owner === SystemProgram, only the System Program can change this account
If owner === TokenProgram, only the Token Program can change this account
If owner === YourProgram, only your program can change this account

This is Solana's security model. You can't hack someone else's account because you don't own it. You can't create tokens because you don't own the token program. You can only modify accounts your program owns.

Exception: Anyone can send SOL to any wallet. The System Program allows this because receiving SOL doesn't modify the wallet's data field — it only changes lamports. Specifically, the System Program says: "Any keypair can increase another account's lamports, but only the keypair owning an account can decrease it."

That's a Solana transaction at its core — accounts changing state, programs enforcing the rules. If you want to understand how that transaction lifecycle actually works and how it differs from a REST API call, I went deep on it in my Week 3 post.

The Account Model in Action: Building an Explorer

To prove this, I built a simple account explorer that queries any address and shows all five fields:

// solana-account-explorer/explorer.mjs
import { createSolanaRpc, address } from "@solana/kit";

const rpc = createSolanaRpc("https://api.devnet.solana.com");

async function inspectAccount(addressString) {
  const acct = address(addressString);

  const [balance, accountInfo] = await Promise.all([
    rpc.getBalance(acct).send(),
    rpc.getAccountInfo(acct).send()
  ]);

  console.log(`Address: ${addressString}`);
  console.log(`Lamports (Balance): ${Number(balance.value)}`);
  console.log(`Owner: ${accountInfo.value?.owner}`);
  console.log(`Executable: ${accountInfo.value?.executable}`);
  console.log(`Data Length: ${accountInfo.value?.data.length} bytes`);
  console.log(`Rent Epoch: ${accountInfo.value?.rentEpoch}`);
}

// Try it:
// node explorer.mjs 11111111111111111111111111111111

This tool runs the exact same query on System Program, Token Program, and a wallet. Same structure, different values.

Run this on any Solana address, and you'll see those five fields. Every account. Always the same structure.

Common Misconceptions

❌ "Wallets are real objects"

✅ Wallets are just accounts with the System Program as owner and empty data. The "wallet" concept is a UI abstraction.

❌ "I own my wallet"

✅ The System Program owns your wallet. Your keypair is the authorization mechanism, not the owner. This is actually safer — you can't accidentally delete your wallet.

❌ "Programs can access any account"

✅ Programs can read any account (it's all public data), but they can only modify accounts they own. This is enforced by the Solana runtime.

❌ "The blockchain stores all your data"

✅ The blockchain stores account states. Your actual data lives in those accounts. Different mental model!

Everything Else Is Just Accounts (Seriously)

Once the five-field structure clicks, everything else becomes obvious:

Transactions - Signed instructions that modify accounts. A transaction is just a request to change the lamports or data field.
Programs - Executable accounts that enforce the rules for modification. They're the gatekeepers.
Tokens - Just accounts owned by the Token Program. The token's supply, decimals, authorities? All in the account's data field.
NFTs - Same structure. Metadata lives in the account's data. The blockchain isn't storing the image; it's storing a pointer in an account.
Wallets - Accounts owned by System Program with no data.
DeFi - Programs managing accounts representing liquidity pools, positions, swaps. Every protocol is just accounts + programs enforcing rules.
AMMs - Programs that maintain accounts for token reserves and user positions.

All of it. Accounts and the programs that manage them.

What to Do Next

Explore it yourself
- Go to Solana Explorer
- Search for any address
- Look for those five fields
Try the inspector

   solana account 11111111111111111111111111111111

This shows you a real System Program account.

Build your own reader

   const connection = new Connection("https://api.devnet.solana.com");
   const accountInfo = await connection.getAccountInfo(publicKey);
   // Now you have: lamports, data, owner, executable, rentEpoch

Understand ownership When building a program, remember: you own accounts your program creates. You can modify them. Users' wallets you can't modify (only System Program can). This shapes how you architect everything.

## The Takeaway

The Solana Account Model is deceptively simple: five fields, one permission rule. That's the entire foundation.

Everything on Solana — wallets, programs, tokens, NFTs, liquidity pools, governance, system clocks, rent — fits perfectly into this structure. There's no special case for "smart contracts" or "user accounts." No complexity hidden in different data structures. Just five fields, repeated across millions of accounts, with one rule controlling who can modify them.

Master this concept, and you've unlocked the mental model for understanding not just Solana, but why Solana is architecturally different from every other blockchain.

Next time someone says "everything is an account," you'll understand exactly why they're right — and why that matters.

Series: The Account Model Foundation

Part 1: The Account Model Explained (this post)
Part 2: Building an Account Explorer (coming May 17)
Part 3: Decoding Account Data (coming May 19)
Part 4: System Program Deep Dive (coming May 21)

What aspect of the account model confused you most? Let me know in the comments — I'll update this post with clarifications!

Part of the 100 Days of Solana Epoch 1 challenge.

How Solana Transactions Are Different from REST API Calls (And Why It Matters)

Lymah — Sat, 09 May 2026 17:25:56 +0000

The Problem: Your Mental Model Is Broken

You know how to build APIs. You understand request/response cycles. You know that a successful POST returns 200 OK, and a failed request returns 400 Bad Request. You've never been charged for a 400.

Solana transactions will break every one of those assumptions.

Last week, I sent a transaction that failed due to insufficient funds. The validator still charged me a fee. A 400 Bad Request just cost me real money. That's when I realized: I was thinking about blockchain like it was an API, and it's not.

In this post, I'm going to show you exactly how Solana transactions work, how they differ from REST APIs, and why understanding those differences will make you a better blockchain developer.

Web2: Request/Response

Here's how you think about HTTP today:

POST /transfer
{
  "recipient": "alice",
  "amount": 100
}

→ Process on server
→ Return result

200 OK: Transfer succeeded
400 Bad Request: Invalid amount
401 Unauthorized: Not authenticated

Key properties:

Stateless (each request is independent)
Synchronous (you wait for a response)
Validated on the server
Failed requests are free (no charge for 400s)
No signature needed (the server trusts TLS)

Web3: Signed State Transitions

Solana transactions are fundamentally different. They're not requests to a server. They're cryptographically signed instructions to change on-chain state.

// Build a transaction
const transaction = new Transaction({
  recentBlockhash: blockhash,
  feePayer: sender.publicKey
});

// Add an instruction
transaction.add(
  SystemProgram.transfer({
    fromPubkey: sender.publicKey,
    toPubkey: recipient,
    lamports: amount
  })
);

// Sign with private key
transaction.sign(sender);

// Send to network
const signature = await connection.sendRawTransaction(
  transaction.serialize()
);

Key differences:

Stateful (changes on-chain state)
Asynchronous (sign locally, then wait for validators)
Validated by the network
Failed transactions still cost fees
Must be signed by the payer's private key

The Fee Problem

Here's the biggest shock: you pay whether the transaction succeeds or fails.

I tried to transfer 3.20 SOL with only 2.20 SOL balance. On an API, that would be a 400:

POST /transfer
400: Insufficient funds
Cost: $0.00

On Solana:

solana transfer 2iHFnuzv... 3.2
Error: Insufficient lamports (need 3.2, have 2.2)
Cost: 0.000005 SOL (~$0.0000005 on mainnet)

I got charged for a transaction that didn't execute.

Why? Because validators did work to process my transaction. They:

Deserialized the signed bytes
Loaded accounts from storage
Executed the System Program instruction
Checked preconditions (balance, signatures, etc.)
Determined it would fail and rejected it

All of that costs compute resources. So they charge a fee. It's economically rational, and it's completely different from REST APIs.

The Three Commitment Levels

With HTTP, you get one response: 200 or error. Solana has three.

When I send a transaction, it moves through these stages:

1. Processed (~400ms)

A validator included my transaction in a recent block.

Waiting for processed... Transaction processed by validator

What it means: A single validator saw your transaction. Not yet secured by consensus.
Risk level: High (1-2% chance it gets forked away)

2. Confirmed (~800ms)

66%+ of validators voted on the block containing my transaction.

Waiting for confirmation from supermajority... Transaction confirmed by network

What it means: Network consensus. You won. It's almost impossible to reverse.
Risk level: Extremely low (no confirmed transaction has ever been reversed in Solana's history)

3. Finalized (~12s)

At least 31 additional confirmed blocks built on top.

Waiting for finalized... Transaction finalized

What it means: Irreversible. Like a database commit that's replicated to disk and backed up.
Risk level: Zero

Compare this to HTTP where you get one response:

HTTP 200 OK immediately
↑
Done. State changed.

Solana transactions are multi-stage. Different applications wait at different levels:

Fast-paced DEX? Wait for "confirmed" (~800ms)
Payment processor? Wait for "finalized" (~12s)
Bridge operation? Wait for even more finalization

Real Code: I Built This

Here's my transfer tool. I send 0.01 SOL to a recipient:

$ node transfer.mjs 6SSAKkUGpyuB2dg81L4d8USfXjpnUXPX6qwif7bcQKwc 0.01

============================================================
  Solana Transfer Tool
============================================================

Connected to Solana devnet
   RPC: https://api.devnet.solana.com

Checking balance...
   Balance: 2.253960000 SOL

Amount: 0.01 SOL (10,000,000 lamports)

Building transaction...
Signing transaction...
Sending to network...
Waiting for processed... Transaction processed by validator

Waiting for confirmation from supermajority... Transaction confirmed by network

Waiting for finalized... Transaction finalized

Transaction successful!

Signature: 4MNtSnAcA2JL3CgwrVqBAoqyhQVpnvog8LKc65MNjKaroTZDj8F8UhpieMnWRLhV6juAbvMypHP92YnaguRmbNGc

View on Solana Explorer:
https://explorer.solana.com/tx/4MNtSnAcA2JL3CgwrVqBAoqyhQVpnvog8LKc65MNjKaroTZDj8F8UhpieMnWRLhV6juAbvMypHP92YnaguRmbNGc?cluster=devnet

Final balance: 2.23895 SOL

This is the Solana equivalent of an HTTP POST. But look at the differences:

I sign the transaction with my private key (HTTP just uses TLS)
I wait through three commitment stages (HTTP returns immediately)
I get a signature instead of a 200 OK (signatures prove finality)
I can view the transaction on a public explorer (no such thing in Web2)

The Secret Weapon: Simulation

Remember how I said failed transactions cost fees?

There's a way around it: simulation.

Before you send a transaction, ask the network: "If I send this, what would happen?"

The network runs your transaction in a sandbox. If it would fail, it tells you. And you don't pay.

// Simulate first (costs nothing)
const simulation = await connection.simulateTransaction(unsignedTx);

if (simulation.value.err) {
  console.log("Would fail:", simulation.value.err);
  // Don't send - you just saved a fee!
} else {
  // Safe to send
  const sig = await connection.sendTransaction(tx);
}

This is the production pattern. Professional Solana apps always simulate before sending. It saves fees and catches errors early.

Mental Model: From Request/Response to State Transitions

Here's how I had to rethink things:

Before (HTTP Thinking)

1. Craft a request
2. Send it
3. Wait for response
4. Response tells me if it worked
5. If it failed, no penalty

After (Solana Thinking)

1. Build a signed transaction (cryptographic proof)
2. Simulate it (does it work? costs nothing)
3. Send it (if simulation passed)
4. Wait through three commitment stages (processed → confirmed → finalized)
5. If it fails, I still paid the fee (even in a sandbox!)

The key shift: You're not making a request to a server. You're proposing a signed change to global state that thousands of validators must agree on.

Why This Matters

Understanding these differences makes you a better blockchain developer because:

You'll design better error handling
- Can't just check for 200 vs 400
- Must handle async multi-stage confirmations
- Must implement retry logic for transient failures
You'll write more efficient code
- Simulate before sending (saves fees)
- Batch multiple operations in one transaction
- Choose the right commitment level for your use case
You'll make economically rational decisions
- Every transaction has a cost
- Failed transactions cost the same as successful ones
- This changes how you architect systems
You'll understand why certain constraints exist
- 1,232 byte transaction size limit (fits in UDP)
- ~90 second blockhash window (network state needs to be fresh)
- Fee charges for failure (validates work done by validators)

The Takeaway

REST APIs lied to you. They made state changes feel free and instantaneous. Solana is honest about it: changing state is work, it takes time, and you pay for it whether it succeeds or fails.

That honesty is uncomfortable at first. But it makes you a better engineer. You start thinking about:

What operations are actually necessary?
How can I batch work to minimize fees?
What happens if this fails?

These are the questions that lead to well-designed systems.

If you're coming from Web2 and feeling lost in blockchain development, this mental shift is everything. Once you stop thinking of transactions as API calls and start thinking of them as cryptographically signed state changes that require network consensus, everything else clicks into place.

Want to experiment? Try building a Solana transfer tool yourself. You'll hit the same realizations I did, and that's where real learning happens.

I Built a Permissionless On-Chain Agent Training Arena on Solana in 3 Weeks

Lymah — Sat, 09 May 2026 16:47:46 +0000

What happens when you put AI agent training on a blockchain, and what I wish someone had told me before I started.

TL;DR: I built a Solana program that logs AI agent training episodes on-chain, making learning verifiable and tamper-proof. Two agents competed in a 10×10 grid. After 50 episodes, the Q-learning agent's average reward climbed from 0.10 to 6.50+. Every step is immutable on devnet. The primitive works. Here's how I got there and what broke along the way.

The Problem Nobody Talks About
What I Built
Why Solana — Not a Database
The Three Instructions
The Agents Actually Learn
The Dashboard
What I Learned
The Numbers
What's Next
Try It

The Problem Nobody Talks About

Here's something that bothered me for a while before I could articulate it clearly.

When someone tells you their AI agent trained for 10,000 episodes and achieved superhuman performance, you have exactly two options: believe them, or don't. There's no third option. No audit trail. No verifiable history. No way to distinguish an agent that genuinely learned from one that someone hardcoded a lookup table for and called "trained behavior."

The entire field of agent training runs on trust. And trust, it turns out, is a terrible foundation for an economy that's supposed to be built on agents doing real work.

I kept thinking about this during the Agentic SWARM Hackathon (Canteen × Colosseum, April–May 2026). The question I kept coming back to was: what would it look like if you couldn't fake it? What if every training step left a permanent, public, verifiable mark?

That's what I spent three weeks trying to build. The result is a small 10×10 grid world with two competing agents. The primitive it demonstrates is not.

What I Built

swarm-arena is a permissionless on-chain agent training arena built on Solana.

Two agents compete in a resource-collection grid world powered by Bevy ECS, a Rust game engine that handles the simulation loop efficiently. After every 200 ticks, an episode ends. The scores get SHA256-hashed alongside the episode state, and that hash gets committed to Solana along with both agents' scores and a timestamp.

Agent reputation accumulates on-chain across episodes. If an agent crosses a score threshold, a SOL reward is released from a vault PDA automatically, no human in the loop.

The live dashboard, two agents competing, 100 episodes committed, Phantom connected.

The live dashboard, two agents competing, 100 episodes committed, Solflare wallet connected.

The stack:

Rust + Bevy ECS: simulation engine. Bevy's ECS architecture made it clean to separate agent components, movement systems, and reward systems
Anchor (Solana): three on-chain instructions handle everything: agent registration, episode logging, and finalization
React + @solana/web3.js: dashboard polling devnet every 5 seconds, showing transactions as they land

The first devnet transaction landed on April 12, 2026:

First confirmed transaction on Solana Explorer, FINALIZED, MAX confirmations

38yieCpWNbex4RDEzXw8pEREHYQNswyW9hYBHXZmigLP9FEmp8FSpDAwPNvU3dcZuY5RrUdWRp6EJcjYJUcEoL21

Getting to that first confirmed transaction took longer than I expected. More on that in a bit.

Why Solana — Not a Database

I got this question a lot during the hackathon, so let me be direct about it.

You could absolutely log training episodes to Postgres. It's faster, easier, and doesn't require learning about PDAs and discriminators. But you'd lose four things that matter a lot once you start thinking about agents as economic actors rather than software demos.

Permissionless. With a database, I control who can write to it. With Solana, anyone with a keypair can call create_agent and start submitting episodes. No API key, no approval process, no terms of service I can revoke on a whim. The program is deployed; it just runs.

Censorship-resistant. I can't delete your agent's training history. Neither can anyone else. If your agent trained 10,000 episodes and built a reputation, that record lives on Solana's ledger permanently. This matters more than it sounds. In a world where agents are doing real economic work, the entity controlling the training ledger has enormous power over the market.

Composable. AgentReputation PDAs are just public Solana accounts. Any other program on the network can read them. A marketplace that wants to rank agents by verified training history, a staking protocol that weights agents by episode count, and a DAO that gates membership by reputation can all be built on top of the same primitive without asking my permission.

A database gives you storage. Solana gives you a shared, trustless, programmable record of who trained what, when, and how well. Those are different things.

The Three Instructions

The entire on-chain economy runs on three Anchor instructions. Keeping it to three was a deliberate choice. I wanted the primitive to be as minimal as possible so it's easy to build on.

create_agent(name: String)
This registers an AgentIdentity PDA, a program-derived account that stores the agent's owner pubkey, a name, and the registration timestamp. It's the agent's permanent on-chain identity. The key insight is that the PDA is derived from the owner's pubkey, so only the keypair holder can register that specific identity. It's censorship-resistant by construction.

log_episode(episode_id, scores, episode_hash)
This is the core. It writes an EpisodeLog PDA with the episode results and increments the agent's AgentReputation PDA, updating total_score and episodes_played. Every call is a permanent mark. You can reconstruct an agent's entire training history from the chain.

finalize_episode(episode_id, score_threshold)
This is where it gets interesting economically. If the winning score meets a threshold, 0.001 SOL transfers from the RewardVault PDA to the winner. No human triggers this. The program does it.

pub fn finalize_episode(
    ctx: Context<FinalizeEpisode>,
    episode_id: u64,
    score_threshold: u64,
) -> Result<()> {
    let log = &mut ctx.accounts.episode_log;
    require!(!log.finalized, ArenaError::AlreadyFinalized);

    let winner_score = log.scores[0].max(log.scores[1]);
    require!(winner_score >= score_threshold, ArenaError::ThresholdNotMet);

    log.finalized = true;

    let reward_lamports = 1_000_000; // 0.001 SOL
    **ctx.accounts.reward_vault.try_borrow_mut_lamports()? -= reward_lamports;
    **ctx.accounts.signer.try_borrow_mut_lamports()? += reward_lamports;

    Ok(())
}

The integration tests cover all three instructions — 4/4 passing against a local validator.

4/4 integration tests passing. create_agent, log_episode, reputation accumulation, finalize_episode

The Agents Actually Learn

Week 1 built the pipeline. Week 2 added Q-learning to Agent 0.

The Q-table maps (state, action) pairs to expected rewards. State is the directional bucket to the nearest resource. Action is one of five moves. After each episode, the table updates based on resources collected and whether Agent 0 beat Agent 1.

The learning curve across episodes:

Episodes	Agent 0 avg reward
1-10	0.10
11-20	0.20
21-30	2.10
31-40	5.10
41-50	6.50+

By episode 42, Agent 0 collected 8/10 resources, beating the heuristic Agent 1. Every step of this learning curve is committed to Solana devnet. The blockchain is the training log.

One of the hackathon organizers asked: "Do you think the agents just memorize the policy given how small the world state is without randomization?"

Yes, with fixed positions and 9 directional states, the agent converges to a memorized lookup table. That's why I switched to randomized resource positions each episode. Slower convergence, but genuine exploration. The same organizer then suggested scaling to Minecraft maps, and that's exactly right. The on-chain primitive is world-agnostic. Any map maker could deploy their world config as a PDA, agents train against it, and reputation accumulates permissionlessly.

The Dashboard

Live at. Built with React + @solana/web3.js + Recharts. Shows:

Agent score totals and win rates across 100 episodes
10×10 arena grid with agent positions
Score history chart showing the Q-learning oscillation
Live transaction feed with Explorer links
Phantom and Solflare wallet connection

The terminal aesthetic was intentional; this is infrastructure, not a consumer app.

What I Learned

The discriminator mismatch will cost you days. Every 0x1004 error is an Anchor instruction discriminator mismatch. Compute SHA256 of "global:{instruction_name}" and take the first 8 bytes. Get this wrong, and nothing works.

Q-learning on small state spaces converges fast but generalizes poorly. If your state space is small enough to memorize, you're doing table lookup, not RL. State space design is the hard part.

On-chain agent training is a primitive, not a product. The 10×10 grid is a proof of concept. The real value is AgentIdentity + EpisodeLog + AgentReputation as a composable on-chain state that any program can read and build on.

The Numbers

Program ID: CCnPxPLd4GbxycDTcP12KP98rWtjKCCNcZC4hqHCB1KV (Solana devnet)
First transaction: April 12, 2026
Episodes committed: 100+
Integration tests: 4/4 passing
GitHub: swarm-arena
Live dashboard: arena-ui

What's Next

Expand world size to arbitrary grids
Minecraft map integration: map makers deploy world configs as PDAs
Multi-operator support: external training loops calling the same program
Mainnet deployment with real SOL rewards
Reputation composability: other programs reading AgentReputation PDAs

Try It

The program is deployed on Solana devnet. Anyone can call create_agent with their own keypair and start submitting episodes. The reputation you accumulate is yours; no central authority can take it away.

That's the point.

If you're building in the agent infrastructure space, the
Canteen Agentic SWARM Hackathon is where this conversation is happening. The quality of technical feedback from the organizers alone made this worth building.

Built during the Agentic SWARM Hackathon by Canteen × Colosseum, April–May 2026.
Stack: Rust, Bevy ECS, Anchor, React, Solana devnet. Find me in the Canteen Discord if you want to run your own agent against the program.

From "Just Data" to "A Global Database": My Second Week Learning Solana

Lymah — Sat, 02 May 2026 22:03:47 +0000

Day 13 of 100 Days of Solana — Reflecting on Reading On-Chain Data

When I started this challenge two weeks ago with Major League Hacking(MLH), I thought blockchain was just a ledger with transactions. I was wrong—and that realization is worth writing about.

The Expectation vs. Reality

Before I touched any code, I imagined blockchain data like this:

Transactions sit in a database somewhere
I'd need special permission to read them
The data would be siloed, private by default
Maybe I'd need to run a full node myself

What I actually found:

I could query a random program address on the internet and instantly see its balance, owner, executable flag, and transaction history. No API key. No permission. No credentials. Just:

const account = await connection.getAccountInfo(publicKey);
console.log(account.lamports); // 2,500,000,000

That moment when I ran npm run inspect and saw my account details appear instantly? That was the click.

The Moment It Clicked: "Public By Default"

On Day 11, I created a comparison table between traditional databases and Solana accounts. The row that hit me hardest was:

Visibility	Database	Solana
	Private by default; you choose what to expose	Public by default; anyone can read any account's data

In Web2, I'm used to databases being fortresses. You build walls, then decide who gets in. On Solana, every account is an open book the moment it exists. The security model is completely inverted.

This isn't a bug. It's the feature.

When I queried the same address on both devnet and mainnet on Day 12, I saw:

Devnet: 0.001159846 SOL, recent transactions, fresh account
Mainnet: 0.069875097 SOL, different transaction history, independent state

Same address. Same blockchain. Different networks. Different data.

It finally made sense: this isn't one database. This is multiple distributed ledgers, all queryable in the same way, all public by design.

The Most Surprising Thing: No JOINs

When I learned that Solana programs can't query each other—that there are no JOINs, no server-side filtering, no SQL—I thought it was a limitation.

It's not.

It's a completely different mental model.

In traditional APIs, I'd hit /users/123/posts and the server would JOIN the users table with the posts table. Solana doesn't work that way. Programs receive accounts as inputs. If I want to "query" related data, I fetch it on the client and assemble it myself.

At first, this felt clunky. Then I realized: this is why Solana is so fast. There's no server deciding how to optimize my query. I get the raw data and compose it however I need.

RPC Calls vs. Traditional APIs

I've worked with REST APIs for years. You know the pattern:

Make a request
Wait for the server to think
Get back JSON
Hope it has what you need

RPC calls feel different. Faster. Simpler.

const signatures = await connection.getSignaturesForAddress(publicKey, { limit: 5 });

This returns transaction signatures. Not a pretty dashboard. Not a summary. Just the data. The API surface is thin. The results are raw.

It's refreshing. It forces me to think about what I actually need, rather than what the API decided to give me.

The Rent Model: Storage That Costs Real Money

This blew my mind: on Solana, storage costs are explicit and tied to your account.

On Day 11, I built a rent calculator. For a 0-byte account: ~890,880 lamports. For a 1000-byte account: ~1,874,880 lamports. The cost scales linearly with data size.

In Web2, storage is abstracted. You pay a monthly AWS bill, somewhere in a spreadsheet. On Solana, you pay per byte. Every byte is yours to manage.

This is radical. And terrifying. And smart.

It means you think about data efficiency. It means bloat has consequences. It means storage is a feature, not an externality.

What Still Confuses Me

✗ Program Derived Addresses (PDAs) — I see them mentioned constantly but haven't built one yet

✗ Cross-program invocations (CPIs) — How do programs call other programs safely?

✗ The difference between accounts and wallets — I understand the technical difference, but the mental model still feels fuzzy

✗ Rent refunds — When I close an account, the lamports come back... to where?

What Clicked This Week

✅ Accounts are objects. Not records in a table. Not documents in a database. Objects with data, an owner, and permissions.

✅ Public data is the default. Not something you have to enable. Something you have to be intentional about hiding.

✅ Same address ≠ same account across networks. Devnet, testnet, mainnet are completely separate blockchains. Your address looks the same; the state is different.

✅ "Reading on-chain data" is just fetching. No joins. No transactions. No consistency guarantees (beyond finality). Just: "Give me this account's data."

For Next Week

I've spent two weeks reading. Next week, I want to write.

Not transactions. Not messages. I want to write data to the blockchain using my own program. I want to understand what happens when I create an account, store something in it, and then modify it.

I want to feel, in my fingers, what it means that the runtime enforces: "Only your program can modify your data."

The Big Picture

Two weeks ago, I thought blockchain was a ledger. Now I think it's a database—a weird one, by Web2 standards, but a database nonetheless.

The rules are different:

No schema
No server
No private data
No join operations
Storage costs are explicit

It feels strange. It feels broken in ways I don't have names for yet.

But it also feels true. And transparent. And distributed.

And that's worth building on.

What surprised you most when you started learning Solana? Drop a comment—I'd love to know.

Catch-up on week 1 write-up here.

Building in public. Learning in public. Days 1-13 of 100.

Traditional Database vs Solana Accounts Comparison

Lymah — Thu, 30 Apr 2026 17:30:20 +0000

Concept	Traditional Database	Solana Accounts
Data Location	Rows in tables on a centralized server	Accounts on a distributed ledger across validators
Schema	Defined by the database (SQL DDL, document schema)	Defined by the owning program; stored as raw bytes in the account's data field
Access Control	Application-level auth (SQL roles, app middleware)	Enforced by the runtime: only the owning program can modify an account, and only with the required signer(s)
Cost of Storage	Server/cloud hosting fees, pay for disk space	Rent-exempt deposit proportional to data size; refundable when the account is closed
Identity/Keys	Auto-increment IDs, UUIDs	32-byte public keys or Program Derived Addresses (PDAs)
Reads	SQL queries, document lookups	RPC calls (getAccountInfo, getProgramAccounts)
Writes	INSERT/UPDATE via application code	Transactions with instructions, signed by authorized keys
Code vs Data	Application code and database are separate systems	Both are accounts; programs (code) and data accounts coexist in the same model
Deletion	DELETE query removes the row	Close the account, lamports are returned to you
Visibility	Private by default; you choose what to expose	Public by default; anyone can read any account's data

Key Differences

1. Data Location

Database: Data lives on centralized servers you control or pay someone to host
Solana: Data is replicated across thousands of validator nodes worldwide

2. Access Control

Database: Enforced by application logic and database permissions
Solana: Enforced at the protocol level - a program cannot modify an account unless it owns it

3. Storage Costs

Database: Monthly hosting fees for infrastructure
Solana: Direct lamport deposit tied to each account - rent-exempt deposit for permanent storage

4. Querying

Database: JOIN operations, server-side filtering, complex queries
Solana: NO JOINS! Programs receive accounts as inputs. Off-chain queries via RPC, then client-side assembly

5. Transparency

Database: Private by default, access controlled
Solana: Public by default, anyone can read any account, anywhere, anytime

Web2 → Web3 Thinking

Web2	Web3 / Solana
Database row = unique record ID (auto-increment, UUID)	Solana account = unique public key (32 bytes)
Authentication = username + password	Authentication = secret key signature
Payment = monthly invoice	Payment = transaction fees (in lamports)
Data privacy = encryption + access control	Data privacy = cryptographic keys (account is public, but only signer can modify)
Backup = database replication	Backup = globally distributed ledger
Admin changes data	Program changes data (signed instruction)

Your Solana Address Is Actually Your SSH Key: Understanding On-Chain Identity

Lymah — Sat, 25 Apr 2026 15:11:24 +0000

If you've ever managed a server, you know SSH keys. You generate a keypair, stick the public key on a server, and suddenly you can prove who you are by signing requests with your private key. The server doesn't care about your username—it cares that you can prove you hold the private key.

Solana identity works the exact same way. And that's the entire revolution.

The Web2 Identity Problem

In Web2, your identity is scattered everywhere. You have:

A username and password on GitHub
A different one on your bank
An email address (that technically belongs to your email provider)
A phone number that the telecom company controls
Social media profiles run by Meta, Google, and X(formerly known as Twitter)

Each one is a separate identity. Each one can be reset, locked, or deleted by the service provider. If GitHub's databases get hacked, your account gets compromised. If you forget your password, you plead with support to reset it. You don't actually own any of these identities—you're renting them.

The problem gets worse: none of these identities talk to each other. When you sign into a new app, you have to create a new account. That app might offer "Sign in with Google," but that's just a bridge—Google still controls the relationship. You still don't own the identity; Google does.

Enter the Keypair

A Solana keypair is fundamentally different. It's two mathematically linked pieces:

Public key (your address, like 9EPnCtdDoYt9...): Anyone can see this. It's like putting your public SSH key on every server simultaneously.
Private key: Only you have this. Sign something with your private key, and anyone can verify you signed it using your public key—without ever seeing the private key.

Here's the mind-blowing part: Nobody issued this keypair to you. You generated it yourself. You own it completely.

You didn't fill out a form. You didn't wait for approval. You ran solana-keygen new, and boom—you have a cryptographic identity that's yours forever. No company can lock you out. No database breach can steal it (unless you were careless with the file). No CEO can revoke it.

What This Enables

Once you have a keypair, suddenly you can:

Own accounts on a blockchain: Instead of a username on GitHub's servers, your public key is your identity on Solana. Any wallet, any dApp, any program knows you by your address. Your identity is portable—use it everywhere.

Sign transactions: Want to move SOL from your account? You sign it with your private key. Want to vote in a DAO? Sign it. Want to approve a smart contract to spend your tokens? Sign it. The Solana network verifies the signature using your public key and executes the transaction. No permission slip needed from a company.

Prove ownership cryptographically: In Web2, you prove you're you by typing a password into their login form. On Solana, you prove it by signing something. The difference: a password can be stolen or brute-forced. A cryptographic signature tied to your keypair is mathematically unbreakable.

Own your data on-chain: Every transaction, every token you hold, every program you interact with—it's all tied to your address. Your financial history is on the blockchain, linked to your identity, not a company's database. You can take this history anywhere.

The Tradeoff

There's a catch. With great ownership comes great responsibility.

If you lose your private key, it's gone forever. No "forgot your password" button. No customer support. This is why Wallet apps give you a seed phrase—12 or 24 words that let you recover your keypair if needed. Lose the seed phrase and the private key, and your account is genuinely locked forever.

In Web2, the company absorbs the risk of losing your account. On Solana, you do. That's the tradeoff for true ownership.

Why This Matters for Web2 Developers

You already use SSH keys. You understand the power of public key cryptography—that's why you use it to authenticate to GitHub and deploy servers without passwords. Solana is taking that exact concept and making it the foundation of identity and ownership across an entire network.

Every dApp, every protocol, every contract you interact with uses the same identity model. Your address is always yours. Nobody can freeze it, lock it, or take it away. The blockchain doesn't have a support team or a privacy policy—it has math.

This is why people say blockchain enables true digital ownership. It's not hype. It's SSH keys everywhere.

Next Steps

Your Solana address is your identity now. Every time you interact with Solana—whether it's checking your balance, sending a transaction, or approving a smart contract—you're using your keypair to prove who you are.

You've already generated one. You've already used it to check your wallet balance and see your transaction history. You own an on-chain identity now.

Welcome to Solana.

Resouces

Follow for more, and you can connect with me here as well.

From Localhost to Production: Deploying an AI Blog Generator (FastAPI + React)

Lymah — Sun, 25 Jan 2026 18:39:41 +0000

Part 2 of building an AI blog generator with FastAPI, React, Hugging Face, Railway, and Vercel.

This post is for developers who’ve built full-stack apps locally and want to confidently ship them to production without overengineering.

Welcome Back!

In Part 1, I built an AI-powered blog generator locally.
In this post, I’ll show how I deployed the full system to production using Railway and Vercel—covering backend deployment, database setup, frontend integration, and the real issues I ran into along the way.

In this post, I'll walk you through:

Deploying the FastAPI backend to Railway
Setting up PostgreSQL in production
Deploying the React frontend to Vercel
Connecting everything together
The challenges I faced and how I solved them

Let's dive in!

Deployment Strategy

Before jumping into deployment, I needed to make some key decisions.

Why Railway for Backend?

I chose Railway over alternatives like Heroku, AWS, or DigitalOcean because:

PostgreSQL Integration - One-click database setup
GitHub Integration - Automatic deployments on push
Developer Experience - Clean UI, clear logs, easy configuration
Pricing - $5/month hobby plan is perfect for side projects
Zero Config - Railway auto-detects Python and handles everything

Why Vercel for Frontend?

Vercel was the obvious choice for the React frontend:

Built for React/Vite - Optimized for frontend frameworks
Global CDN - Lightning-fast content delivery
Automatic HTTPS - SSL certificates out of the box
Preview Deployments - Every PR gets its own URL
Free Tier - Perfect for personal projects

Architecture Overview

Here's what we're building:

┌─────────────┐     HTTPS      ┌─────────────┐
│             │◄───────────────►│             │
│   Vercel    │                 │   Railway   │
│  (Frontend) │                 │  (Backend)  │
│             │                 │             │
└─────────────┘                 └──────┬──────┘
                                       │
                                       │
                                ┌──────▼──────┐
                                │ PostgreSQL  │
                                │  Database   │
                                └─────────────┘

Simple, scalable, and cost-effective.

Part 1: Deploying Backend to Railway

Step 1: Preparing the Backend

Before deployment, I needed to ensure the backend was production-ready.

Creating railway.json

Railway uses this file to understand how to deploy our app:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "uvicorn app.main:app --host 0.0.0.0 --port $PORT",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Key points:

NIXPACKS auto-detects Python and installs dependencies
--host 0.0.0.0 allows external connections
$PORT uses Railway's dynamic port assignment
Restart policy handles crashes gracefully

Updating Production Dependencies

Made sure requirements.txt included production essentials:

fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy==2.0.23
psycopg2-binary==2.9.9  # PostgreSQL driver
pydantic==2.5.0
pydantic-settings==2.1.0
python-dotenv==1.0.0
requests==2.31.0
gunicorn==21.2.0  # Production server

Step 2: Setting Up Railway

Creating the Project

The process was surprisingly smooth:

Went to railway.app
Clicked "Start a New Project"
Selected "Deploy from GitHub repo"
Chose my ai-blog-generator repository
Important: Selected backend as the root directory

Railway immediately started building!

Adding PostgreSQL

This was the easiest database setup I've ever done:

Click "New" → "Database" → "PostgreSQL"

Railway automatically:

Provisioned a PostgreSQL instance
Created the DATABASE_URL environment variable
Connected it to my backend service

No configuration files, no manual connection strings - just magic.

Step 3: Environment Variables

Railway makes environment management clean and secure.

I added these variables via the Railway dashboard:

HUGGINGFACE_API_KEY=hf_xxxxxxxxxxxxx
HUGGINGFACE_MODEL=meta-llama/Llama-3.3-70B-Instruct
ENVIRONMENT=production
APP_NAME=AI Blog Generator API
VERSION=1.0.0

Pro tip: The DATABASE_URL was automatically set when I added PostgreSQL. No manual configuration needed!

Step 4: First Deployment Attempt

I pushed my code and watched the build logs:

git add .
git commit -m "Prepare for Railway deployment"
git push origin main

Railway detected the push and started building...

And it failed. 😅

Challenge #1: Import Errors

The Problem:

ModuleNotFoundError: No module named 'app.database'

The Cause:

My local environment had different import paths than production.

The Solution:

I realized I needed to ensure all imports were relative to the backend directory. Updated app/main.py:

# Before (worked locally)
from database import engine, Base

# After (works everywhere)
from app.database import engine, Base

Lesson learned: Always test imports from the project root!

Challenge #2: Database Tables Not Created

The Problem:

API worked, but generating blogs failed with:

relation "blog_posts" does not exist

The Cause:

FastAPI wasn't creating tables on startup in production.

The Solution:

Updated the lifespan context manager in main.py:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: Create tables
    print("Creating database tables...")
    Base.metadata.create_all(bind=engine)
    print("Tables created successfully!")
    yield
    # Shutdown
    print("Application shutting down")

app = FastAPI(lifespan=lifespan)

Now tables are created automatically on every deployment!

Step 5: Generating a Domain

Railway provides a free subdomain:

Settings → Networking → Generate Domain

Got: https://ai-blog-generator-production-bd0c.up.railway.app

Tested it:

curl curl https://ai-blog-generator-production-bd0c.up.railway.app/health

# Response:
{"status":"healthy","environment":"production"}

Backend deployed successfully!

Part 2: Deploying Frontend to Vercel

Step 1: Preparing the Frontend

Environment Configuration

Created .env.production:

VITE_API_URL=https:/https://ai-blog-generator-production-bd0c.up.railway.app

This tells the frontend where to find the backend in production.

Vercel Configuration

Created vercel.json for optimal deployment:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

The rewrites section ensures React Router works properly in production.

Step 2: Deploying to Vercel

Import from GitHub

Logged into vercel.com
Clicked "New Project"
Selected my repository
Critical: Set root directory to frontend

Build Configuration

Vercel auto-detected everything:

Framework: Vite
Build Command: npm run build
Output Directory: dist
Install Command: npm install

Adding Environment Variable

Added the most important variable:

VITE_API_URL = https://ai-blog-generator-production-bd0c.up.railway.app

Clicked "Deploy" and waited...

First deployment: Success!

Got URL: https://frontend-ochre-rho-71.vercel.app/

Challenge #3: CORS Errors

Opened my Vercel URL and... nothing worked.

The browser console showed:

Access to fetch at 'https://ai-blog-generator-production-bd0c.up.railway.app/api/v1/generate' 
from origin 'https://frontend-ochre-rho-71.vercel.app' has been blocked by CORS policy

The Problem:

The backend wasn't configured to accept requests from the Vercel domain.

The Solution:

Added CORS_ORIGINS to Railway:

CORS_ORIGINS=https://frontend-ochre-rho-71.vercel.app

Railway auto-redeployed the backend with new CORS settings.

Hard refreshed the frontend (Ctrl+Shift+R) and...
Connected! The status indicator turned green!

Testing in Production

First Blog Generation

Held my breath and tried generating a blog:

Input:

Topic: The Future of Cloud Computing
Tone: Professional
Length: Medium
Keywords: cloud, scalability, innovation

Clicked "Generate Blog Post"...

20 seconds later...

Success!

Title: The Future of Cloud Computing: Embracing Innovation and Scalability

Word Count: 1,247 words
SEO Score: 82

[Full formatted blog content displayed]

Everything worked:

✅ AI generation
✅ Database storage
✅ SEO scoring
✅ Copy to clipboard
✅ Download as Markdown
✅ Blog history

Performance Testing

I generated several blogs to test:

Response Times:

API health check: ~50ms
Blog generation: 25-35 seconds (AI processing)
Blog retrieval: ~100ms
Blog list: ~150ms

Database:

Tables created automatically ✅
Blogs saving correctly ✅
Queries performing well ✅

Challenges & Solutions Summary

Let me share all the issues I encountered and how I solved them:

1. Module Import Errors

Error:

ModuleNotFoundError: No module named 'app.database'

Solution:
Ensured all imports were absolute from the project root:

from app.database import engine
from app.models.blog import BlogPost
from app.services.ai_service import hf_service

2. Database Tables Not Created

Error:

psycopg2.errors.UndefinedTable: relation "blog_posts" does not exist

Solution:
Added lifespan context manager to create tables on startup:

@asynccontextmanager
async def lifespan(app: FastAPI):
    Base.metadata.create_all(bind=engine)
    yield

app = FastAPI(lifespan=lifespan)

3. CORS Policy Blocking Requests

Error:

Access to fetch has been blocked by CORS policy

Solution:
Added frontend URL to CORS_ORIGINS in Railway:

CORS_ORIGINS=https://ai-blog-generator.vercel.app

4. Environment Variables Not Loading

Error:
Frontend couldn't connect to backend (showing localhost URL)

Solution:
Ensured VITE_API_URL was set in Vercel's environment variables for all environments (Production, Preview, Development).

5. Hugging Face API 503 Errors

Error:

Model is currently loading

Solution:
This is expected! Hugging Face models go to sleep after inactivity. My retry logic handles it:

if response.status_code == 503:
    print("Model loading... waiting 30 seconds")
    time.sleep(30)
    continue  # Retry

After the first request warms up the model, subsequent requests are fast.

Production Optimizations

Backend Optimizations

1. Database Connection Pooling

engine = create_engine(
    settings.DATABASE_URL,
    pool_pre_ping=True,    # Verify connections
    pool_size=10,          # Connection pool
    max_overflow=20        # Max additional connections
)

2. Request Timeout Handling

response = requests.post(
    self.api_url,
    headers=self.headers,
    json=payload,
    timeout=120  # 2 minute timeout
)

3. Logging for Production

Added proper logging to track issues:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# In routes
logger.info(f"Generating blog for topic: {request.topic}")
logger.error(f"Generation failed: {str(e)}")

Frontend Optimizations

1. Environment-based API URL

const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000';

2. Error Boundaries

Added proper error handling:

try {
  const result = await blogAPI.generateBlog(formData);
  setCurrentBlog(result);
  setSuccess(true);
} catch (err) {
  const errorMessage = err.response?.data?.detail || 'Failed to generate blog';
  setError(errorMessage);
}

3. Loading States

Clear feedback during long operations:

{isGenerating ? (
  <>

    Generating Content...
  </>
) : (
  <>

    Generate Blog Post
  </>
)}

Cost Breakdown

Let's talk money - one of the best parts!

Railway (Backend + Database)

Hobby Plan: $5/month

Includes backend hosting
PostgreSQL database (1GB storage)
Automatic backups
99.9% uptime SLA

Free Trial:

$5 credit/month for free accounts
Perfect for side projects and portfolios

Vercel (Frontend)

Hobby Plan: FREE

Unlimited personal projects
100GB bandwidth/month
Global CDN
Automatic HTTPS
Custom domains

Hugging Face

Free Tier

Inference API included
Rate limits apply (but generous)
Models sleep after inactivity
Perfect for demos and low-traffic apps

Total Monthly Cost

$0 - $5/month depending on Railway usage!

For a production-ready, full-stack AI application, that's incredible value.

CI/CD Pipeline: Auto-Deployment

The best part? Both platforms auto-deploy when I push to GitHub!

How It Works

# Make changes
git add .
git commit -m "Add new feature"
git push origin main

# Automatically:
# 1. Railway detects push
# 2. Builds backend
# 3. Runs tests
# 4. Deploys new version
# 5. Zero downtime!

# Similarly:
# 1. Vercel detects push
# 2. Builds frontend
# 3. Deploys to CDN
# 4. Instantly live!

Deployment time: 2-3 minutes for both!

Deployment Logs

Railway and Vercel both provide detailed logs:

Railway logs showed:

Building...
├─ Installing dependencies
├─ Building application  
└─ Starting server

✓ Deployment successful
✓ Health check passed

Vercel logs showed:

Building...
├─ Installing dependencies
├─ Running build
├─ Optimizing assets
└─ Uploading to CDN

✓ Build completed
✓ Deployment live

Monitoring & Maintenance

Railway Monitoring

Railway dashboard shows:

CPU Usage: ~5-10% average
Memory: ~150MB
Response Times: 50-100ms (excluding AI)
Uptime: 99.9%

Vercel Analytics

Enabled Vercel Analytics (free!) to track:

Page views
User locations
Performance metrics
Core Web Vitals

Database Monitoring

Checked PostgreSQL usage:

Storage: ~5MB (100 blog posts)
Connections: 2-3 active
Queries: Fast (<100ms)

Everything running smoothly!

Lessons Learned

Here are the key takeaways from this deployment journey:

1. Start with Simple Deployment

Don't overcomplicate. Railway and Vercel handle 90% of DevOps for you.

2. Environment Variables Are Critical

Spent hours debugging before realizing a typo in VITE_API_URL. Triple-check these!

3. CORS Will Get You

Always configure CORS properly. Test with actual frontend URL, not localhost.

4. Database Initialization Matters

In production, tables won't magically appear. Handle database setup in application lifecycle.

5. Logs Are Your Best Friend

Both Railway and Vercel have excellent logging. Use them to debug issues.

6. Test Production Early

Deploy early, deploy often. Catching issues in production is better than finding them in interviews!

7. Free Tiers Are Powerful

You can build and deploy production apps for $0-5/month. No excuses!

Future Improvements

Now that we're in production, here's what I'm planning:

Immediate (This Week)

[ ] Add rate limiting to prevent abuse
[ ] Set up error monitoring (Sentry)
[ ] Add database backup automation
[ ] Create health check monitoring

Short-term (This Month)

[ ] Add user authentication
[ ] Implement blog favorites
[ ] Add export to PDF
[ ] Create API documentation site

Long-term (This Quarter)

[ ] Multi-language support
[ ] Image generation for blogs
[ ] Content scheduling
[ ] Analytics dashboard
[ ] WordPress integration

Final Thoughts

Deploying this project taught me more than months of tutorials ever could.

What worked well:

Railway's automatic PostgreSQL setup
Vercel's instant deployments
GitHub integration for CI/CD
Simple, clean architecture

What I'd do differently:

Set up monitoring from day one
Add comprehensive error logging earlier
Test with production environment variables locally
Document deployment steps as I go

Most importantly: I now have a live, working application in my portfolio. Something I can show in interviews, share with friends, and actually use!

Resources

Tools and platforms used:

Railway
Vercel
Hugging Face
FastAPI
React

Documentation that helped:

Try It Yourself!

Live Demo

GitHub Repository

The complete code is open source! Feel free to:

Star the repository
Fork and customize
Report issues
Submit pull requests

This project reinforced that deployment is where architectural decisions are validated—and where many “working” projects quietly fail

🙏 Thank You!

Thanks for following along on this journey!

Part 1 covered the development process.

Part 2 (this post) covered deployment.

What did you learn? What would you do differently? Drop a comment below!

If you found this helpful:

❤️ Like this post
💬 Leave a comment
🔄 Share with others
👀 Follow me for more content

Connect With Me

I'd love to hear your thoughts and answer questions!

GitHub
Twitter(X)
LinkedIn

What's Next?

I'm already working on v2.0 with exciting features:

🔐 User authentication
🖼️ AI-generated blog images
📅 Content scheduling
📊 Analytics dashboard

Stay tuned! Follow me to get notified when the next update drops.

DEV Community: Lymah

Transfer Fees, Metadata, and Soulbound Tokens: A Tour of Solana Token Extensions

Where I Started

1: Your First Mint (It's Just an Account)

2: Metadata — Giving Your Token an Identity

3: Transfer Fees — Economics Without Middleware

4: The Full Lifecycle in One Run

What I'd Tell Myself at the Start

What's Next

Solana's System Program: Understanding the Kernel

The Question That Started It All

What is the System Program?

Core Insight: Programs Own Accounts, Not People

The System Program's Four Main Instructions

1. CreateAccount

2. Transfer

3. Allocate

4. Assign

Example: The Lifecycle of Creating an Account

Rent: The System Program's Economic Rule

Seeing It Through the Explorer

Why This Design?

Consistency

Security

Economics

Auditability

System Program vs. Ethereum

Debugging: Common System Program Errors

"Account does not have enough lamports."

"Account is not owned by the System Program"

"Cannot allocate more space"

What to Do Next

Wrapping Up Epoch 1

Decoding Solana Account Data: Three Methods Compared

From Hex to Human-Readable

The Problem

Background: Account Data is Binary Borsh

Method 1: Using a Codec Library

Method 2: Manual Byte-Level Parsing

Method 3: RPC's jsonParsed Format

Comparison: Real Results

Deciding Which to Use

Real-World Example: Parsing Token Account Data

The Key Insight

Practical Debugging

The Full Example

Challenge

Building a Solana Account Explorer: Query On-Chain Data Like a Database

From Concept to Code

What We're Building

Setup

The Full Code

What the Output Taught Me

The System Program owns itself — sort of

The Token Program is only 48 bytes — but controls everything

A wallet with 0 bytes of data is a complete account

Three Things Worth Noticing in Your Own Queries

The KNOWN_PROGRAMS Map — Why It Matters

Try It Yourself

What's Next

# Week 4: Understanding Solana’s Account Model as a Web2 Developer

The Core Idea

A Web2 Analogy

Programs vs Accounts

Programs

Accounts

Ownership Matters

Rent and Storage

Why This Model Exists

Example Mental Model

Final Thoughts

The Solana Account Model Explained: Everything is an Account

The Aha Moment

What Is an Account? The Five-Field Structure

Understanding Each Field

Three Account Types: Wallets, Programs, and Sysvars

Type 1: Your Wallet (A Data Account)

Type 2: The Token Program (An Executable Account)

Type 3: Clock Sysvar (A System Data Account)

Why This Matters: Three Real-World Scenarios

The `KNOWN_PROGRAMS` Map — Why It Matters