Forem: Divine Igbinoba

Atlas Payroll: Streaming Payroll with Operational Capital Yield on Solana

Divine Igbinoba — Sat, 21 Mar 2026 21:15:49 +0000

Introduction

Atlas Payroll is a Solana smart contract that reimagines how corporate payroll and idle operational capital are managed. Instead of letting company funds sit dormant in a commercial bank account earning little to no interest, Atlas routes those funds into Kamino Finance (a Solana native lending protocol) to earn yield on the deposited capital. At the same time, employees are paid in real time. Their salary accrues every second and can be withdrawn at any point.

While this architecture is general enough to be applied in other contexts, it was designed specifically with corporate payroll and operational treasury management in mind, giving employers a way to put idle operational capital to work whilst giving employees liquidity on demand.

System Overview

The protocol revolves around five participants:

The Capital Provider (Operator): Deposits funds that are routed to Kamino Finance to earn yield. In a corporate context, this is the employer or treasury manager.
The Recipient (Employee): Pay accrues per second and can be withdrawn at any time.
Kamino Finance: The external lending protocol that earns yield on the deposited USDC.
The Safety Vault: An on-chain USDC token account that holds at least two days' worth of total payroll at all times, providing a liquidity buffer in case Kamino is temporarily illiquid.
The Keeper: An off-chain agent that monitors employee claim, operator withdrawal, and staff offboarding events to infer when the safety vault balance has been reduced. When a rebalance is warranted, it calls the rebalance instruction and earns a $1 USDC bounty per successful call.

Operational Flow

The operator initialises their protocol vault account on-chain.
The operator deposits USDC from an external wallet; the contract routes it directly into Kamino Finance, receiving kUSDC (Kamino's yield bearing collateral token) in return.
The operator initialises employee accounts, specifying each employee's annual salary. The contract derives the per second pay rate and begins accruing salary from that moment.
The keeper monitors the vault balance off-chain. When it detects that the safety vault has fallen below the two-day payroll threshold, it calls the rebalance instruction, which withdraws enough USDC from Kamino to top up the vault, and earns its bounty.
The operator may withdraw capital from Kamino at any time, subject to the constraint that they cannot withdraw funds that are owed to employees (i.e., the total liability is always preserved).
Employees call the claim instruction to withdraw their accrued salary. Funds are pulled from the safety vault first; if the vault balance is insufficient, the shortfall is sourced directly from Kamino.
When an employee is offboarded, all outstanding pay is sent to them immediately, their accrual stops, and their rate is removed from the global payroll rate.
Once an employee account has a zero outstanding balance, the operator can close it and reclaim the on-chain rent (SOL storage deposit).

Architecture

The protocol is divided into three logical sub systems:

Operator architecture: Deposit, withdraw, and capital management.
Employee architecture: Salary accrual, claim, offboarding, and account closure.
Rebalance architecture: Moving funds from Kamino yield into the safety vault.

Technical Stack

Atlas Payroll is written in Rust using the Anchor framework (v0.32.1) and deployed on the Solana blockchain.

key dependencies (Cargo.toml):

[package]
name = "anchor-payroll-capstone-q1-26"
version = "0.1.0"
edition = "2021"

[dependencies]
anchor-lang    = { version = "0.32.1", features = ["init-if-needed"] }
anchor-spl     = { version = "0.32.1" }
solana-program = "2.3.0"
bytemuck       = { version = "1.20.0", features = ["min_const_generics"] }

Toolchain requirements: Rust (stable), Solana CLI, Anchor CLI v0.32.1, Node.js (for tests), and Surfpool (for local testnet with mainnet account cloning).

Contract Data Structures

General Notes on Types

All account public keys are stored as Pubkey (32 byte unsigned integers). All token amounts are stored as u64 (unsigned 64 bit integers), which can represent values up to approximately 1.8 × 10¹⁹. This comfortably accommodates USDC amounts expressed in their smallest unit (micro-USDC, 6 decimal places), allowing the contract to represent hundreds of millions of dollars without overflow.

1. The Operator Account (`ProtocolVault`)

Fields Type and Description

update_liability (Update Liability)

This method is called at the beginning of most instructions to ensure the recorded liability is current before any financial logic is executed:

new_liability = liability + (global_rate × (current_time - liability_timestamp))
liability_timestamp = current_time

`update_protocol` (Safety Vault Requirement Check)

This method calculates how much USDC needs to be transferred from Kamino into the safety vault in order to bring the vault back up to the required two day buffer:

required = (global_rate × 2.2 days in seconds) - safety_amount

The 2.2-day multiplier (rather than exactly 2.0) provides a small operational buffer to account for network latency, keeper scheduling delays, and minor fluctuations.

`calculate_k_pool (`Kamino Pool Valuation)

This is one of the more technically complex parts of the contract. It reads the Kamino Reserve account directly from raw bytes using zero-copy deserialisation (via bytemuck) to avoid the compute cost of standard Anchor deserialisation.

It returns a tuple of (total_pool_usdc, total_ktoken), representing the total USDC liquidity in the Kamino reserve and the total supply of kUSDC tokens respectively. These two values form the exchange rate used to convert between kUSDC and USDC throughout the contract.

Important implementation detail

Kamino stores its liquidity values using a u68.60 fixed point format (also referred to as "scaled fraction" (_sf ) suffix in field names).

The scale factor is 2^60 = 1,152,921,504,606,846,976, which is different from the standard Solana convention of 10^18. This is a critical distinction: using the wrong WAD value would produce wildly incorrect exchange rate calculations.

Source: deepwiki.com/Kamino-Finance/klend

Kamino's IDL defines several liquidity fields as u128 (e.g., borrowed_amount_sf, accumulated_protocol_fees_sf). However, because Solana on-chain accounts begin with an 8 byte discriminator, subsequent fields are statistically more likely to be 8 byte aligned than 16 byte aligned.

Since bytemuck requires strict alignment guarantees that cannot be assured for u128 (which requires 16 byte alignment) in this context, these fields are split into two u64 values in the contract's struct definition and then reconstructed into a u128 at runtime:

Source: github.com/solana-foundation/anchor/issues/3114

The total USDC in the pool is then computed as:

total_pool_usdc = (available_amount + borrowed_amount - protocol_fees - referrer_fees - pending_referrer_fees) / wad

`calculate_total_assets` (Net Available Capital)

This function computes the total USDC value the operator can access, net of all employee liabilities:

It converts the protocol's kUSDC balance to its USDC equivalent using the pool ratio, adds the safety vault balance, and then subtracts the current total liability (recalculated to the present moment using global_rate and liability_timestamp). This is the number checked before allowing any operator withdrawal.

`ktoken_to_burn (`Redemption Calculation)

Given a required USDC amount, this function calculates the exact number of kUSDC tokens that must be redeemed from Kamino to receive at least that amount:

ktoken_to_burn = ceil(usdc_required × total_ktoken / total_pool_usdc)

Ceiling division is used deliberately to ensure the protocol never under redeems. Without rounding up, integer truncation could result in receiving slightly less USDC than required:

The current mint_total_supply (total kUSDC in circulation) is read via manual byte offset deserialisation because this specific field is not always accessible without unpacking the full reserve struct:

2. The Employee Account (`StaffAccount`)

Fields Type and Description

`claimable_salary`

This calculates the amount the employee can currently withdraw:

effective_time = if !active && time_ended != 0 { time_ended } else { now }
claimable = (effective_time - time_started) × rate - total_claimed

When an employee has been offboarded (active = false), time_ended is used as the cutoff ensuring no further salary accrues after offboarding, while still allowing the employee to withdraw any remaining unclaimed balance.

3. Kamino's Reserve Account (`Reserve`)

The Kamino Reserve struct is a large on-chain account maintained by the Kamino lending protocol. This contract does not own or write to it; it reads from it to obtain the data needed for exchange rate calculations.

Fields of relevance to this contract:

Helpers

Instruction Discriminator

Anchor programs identify instructions by an 8 byte discriminator derived from the global namespace prefix and the instruction name. Since this contract calls Kamino via raw CPI (Cross Program Invocation) rather than through an Anchor generated client, it must construct this discriminator manually:

Key Constants

Instructions

1. Operator Initialisation (OperatorInit)

This instruction creates and initialises the ProtocolVault account for a given operator. A single operator can only ever have one protocol vault. The PDA seed is derived solely from the operator's public key, making it impossible to initialise a second vault with the same wallet:

This enforces a one to one relationship between an employer and their payroll contract instance, preventing duplicate accounts and simplifying account resolution.

Accounts required:

operator: Signer and rent payer.
protocol: The PDA account to be initialised (ProtocolVault).

The following are solana system level programs required by almost every instruction in this contract:

system_program : Solana's built-in program responsible for the fundamental account lifecycle.
token_program : holds exclusive write authority over all SPL token accounts (ATAs)
associated_token_program: derives and creates the associated token account (ATA) address for a given wallet and mint

TokenInterface is used instead of Program<Token> to maintain compatibility with both the original SPL Token program and the newer Token-2022 program:

Instruction logic:

The protocol vault is initialised with all amounts set to zero and liability_timestamp set to the current clock time, establishing the baseline for future liability calculations. set_inner is Anchor's method for serialising a fully constructed struct into an account in one atomic operation:

2. Operator Deposit (Deposit)

The operator deposits USDC from their wallet into Kamino Finance. The contract constructs and fires a CPI call to Kamino's deposit_reserve_liquidity instruction, which transfers USDC from the operator's associated token account and mints kUSDC into the protocol's kUSDC token account.

Key accounts:

operator: Signer (the account paying USDC into the pool).
protocol_authority: Derived from [b"authority", protocol.key()]. This PDA is the program-controlled authority over all protocol owned token accounts (USDC and kUSDC):
protocol_ktoken_ata: The protocol's associated token account for kUSDC. Kamino deposits collateral tokens here after each deposit:
instruction_sysvar: Kamino performs introspection on the current transaction's instruction set as a security check. This account must be present:

Kamino specific accounts:

These accounts are required by Kamino's program and are passed through with /// CHECK: since Anchor does not natively own or validate them, Kamino's program enforces their correctness on its side.

kamino_program: The on-chain program ID of Kamino Finance. This is the address of the deployed Kamino lending program on Solana mainnet. Source: github.com/Kamino-Finance/klend
reserve: The address of the USDC Kamino reserve account. This account holds all state for the lending market including ReserveCollateral (kUSDC supply data) and ReserveLiquidity (USDC liquidity data). It is the account this contract reads from in calculate_k_pool.
lending_market: The specific Kamino lending market this contract interfaces with, in this case the main USDC market.
reserve_liquidity_mint: The mint address of the token used in this market, which is USDC. This tells Kamino which token is being deposited.
reserve_liquidity_supply: The address of the total liquidity supply pool for this reserve. This is the Kamino controlled vault that holds all deposited USDC.
reserve_collateral_mint: The mint address of the yield bearing collateral token Kamino issues in exchange for a deposit (kUSDC). This token is the mechanism through which yield is realised: as borrowers pay interest into the pool, the kUSDC-to-USDC exchange rate increases, meaning the same kUSDC balance becomes redeemable for more USDC over time. Returning kUSDC to this mint via redeem_reserve_collateral burns it and releases the underlying USDC plus accrued interest.

Why **Box<InterfaceAccount<...>>?** Solana's BPF runtime enforces a 4KB stack limit per frame. Wrapping large account types in Box<> heap-allocates them, preventing stack overflows when multiple large accounts are in scope simultaneously.

Instruction logic:

update_liability() is called first to ensure the protocol's employee debt record is current before any funds move. The kUSDC balance is snapshotted before the CPI, then diffed against the post-CPI balance after reload() to determine exactly how many kUSDC tokens Kamino minted. Without reload(), the in-memory account struct would still reflect the pre-CPI balance:

Why **invoke vs invoke_signed?*invoke *is used here because the operator is the top-level signer and is already declared in the accounts struct. invoke_signed is required only when a PDA needs to act as a signer. The seeds must be provided so the runtime can verify the PDA derivation before granting signing authority:

Why are accounts listed twice?AccountMeta carries the metadata Solana needs to validate accounts and calculate the compute budget (public key, writable flag, signer flag). The raw AccountInfo slice passed to invoke carries the actual account data (lamports, data bytes, owner, and the executable flag). Both are required:

3. Operator Withdrawal (CFOWithdraw)

The operator can withdraw USDC from the protocol's capital at any time, subject to one hard constraint: the total amount owed to all employees is always preserved. calculate_total_assets returns net available capital, the total USDC value of all assets minus current liability and any withdrawal request beyond this ceiling fails immediately.

Instruction logic:

If the requested amount exceeds what is currently in the safety vault, the shortfall is first redeemed from Kamino before the final transfer. The safety vault is always the first source because it is the most immediately liquid. Redeeming from Kamino incurs additional compute cost and potential minor slippage at scale:

invoke_signed is used for the Kamino redemption (unlike deposit) because protocol_authority must sign the redemption on the protocol's behalf. The signer seeds are constructed and passed as follows:

debit_safety uses these same seeds to authorise the final USDC transfer from the protocol's token account to the operator's wallet:

4. Rebalance (R`ebalance`)

The rebalance instruction is called by the keeper (an off-chain monitoring agent) which watches for employee claim, operator withdrawal, and staff offboarding events to infer when the safety vault has likely been drawn down. The keeper earns a fixed $1 USDC bounty per successful call, and the platform earns a 0.5% fee on the total amount moved from Kamino.

Key accounts (additions over withdrawal):

keeper: Signer. The off-chain agent calling the instruction.
keeper_ata: The keeper's USDC token account, where the bounty is sent.
platform: The platform treasury public key.
platform_ata: The platform's USDC token account, where the 0.5% tax is sent.

Instruction logic:

update_protocol() computes the USDC deficit: how much needs to move from Kamino to restore the full two-day buffer. This required amount is capped at max_claimable (the USDC equivalent of the protocol's entire kUSDC balance) to prevent over redemption:

The bounty and tax are then computed:

Two guards protect the keeper from wasted fees. The first fires before any Kamino interaction so that if the vault is already adequately funded, or if the available yield is smaller than the total cost to rebalance, the instruction returns Ok(()) silently. The second fires after the redemption, in case the USDC actually received from Kamino falls short due to rounding:

After both guards pass, the bounty and tax are dispatched and the remainder is credited to protocol.safety_amount:

5. Staff Initialisation (S`taffInit`)

The operator initialises an employee account, specifying the employee's annual salary in micro-USDC. Annual salary is the standard unit in employment contracts; the contract converts it to a per second rate internally:

rate_per_second = annual_salary / 31,557,600

31,557,600 is the number of seconds in an average Gregorian year (365.25 × 86,400), which correctly accounts for leap years.

The PDA seed is derived from the employee's wallet address, meaning each employee can only ever have one active account per protocol. The payer = operator constraint gives the operator authority to later close the account and reclaim the rent:

Instruction logic:

update_liability() is called first to checkpoint the existing accumulated debt before adding the new employee's rate. If this step were skipped, the new rate would retroactively inflate the liability calculation back to liability_timestamp, over-counting what the protocol owes. The per second rate is then added to protocol.global_rate, immediately factoring into all future liability calculations:

6. Staff Claim (StaffClaim)

An employee calls this instruction to withdraw their accrued salary at any time.

Instruction logic:

claimable_salary() is called on the StaffAccount to compute the exact amount owed. If the claimable amount exceeds the safety vault balance, the shortfall is sourced directly from Kamino rather than failing the transaction. The protocol prioritises ensuring employees receive their pay even when the keeper has not rebalanced recently:

A MINIMUM_CLAIM guard protects against "gas attrition" a scenario where the transaction fee to execute the claim exceeds the value being claimed, leaving the employee worse off.

If the claimable amount falls below this threshold the claim reverts, and the employee is advised to wait for additional accrual. staff_account.total_claimed is then incremented to track the employee's cumulative lifetime withdrawals, and protocol.liability is decremented by the claimed amount to keep the liability register accurate:

7. Staff Offboarding (‎StaffOffboard)

The operator calls this instruction to terminate an employee's salary accrual and send all outstanding pay in a single atomic transaction.

The account struct includes a constraint = staff_account.active == true guard, making it impossible to accidentally offboard an employee twice. active and time_ended are updated before the payment logic executes, so even in the illiquid edge case the employee's accrual is permanently stopped while any unpaid balance remains claimable via staff_claim:

Instruction logic:

All remaining pay is then transferred to the employee using the same vault-first, Kamino fallback logic as staff_claim. In the rare edge case where neither the vault nor Kamino has sufficient USDC to cover the full final payment, the employee is offboarded and a warning is emitted keeping the remaining balance claimable:

8. Collect Staff (CollectStaff‎)

Once an employee has been offboarded and has claimed all outstanding pay, the operator closes the StaffAccount on-chain, freeing storage and reclaiming the SOL rent deposit.

Instruction logic:

claimable_salary() is the critical safety gate ensuring that if any balance remains unclaimed, the close is rejected entirely. This ensures the operator cannot inadvertently destroy an account that still holds an employee's earned funds:

The close = operator Anchor constraint handles the rest: once the instruction succeeds, Anchor zeroes out the account data and transfers all remaining lamports to the operator's wallet at the end of the transaction:

Testing Strategy

Testnet Setup with Surfpool

Testing this contract against Kamino is non-trivial because Kamino's lending markets only exist on mainnet. The approach taken here is to clone the mainnet state into a local test environment using Surfpool (a Solana test validator that supports cloning mainnet accounts).

Finding the USDC Kamino Reserve:

The test setup queries the mainnet RPC using getProgramAccounts with two memcmp filters, one matching the target lending market address at byte offset 32, and one matching the USDC mint at byte offset 128 (the positions of lending_market and liquidity_mint respectively within the Reserve struct). This returns the exact reserve account without needing to know its address in advance:

Deriving dependent addresses from the cloned reserve:

LENDING_MARKET_AUTHORITY is derived via findProgramAddressSync using the lma seed prefix that Kamino uses for all lending market authority PDAs:

RESERVE_LIQUIDITY_SUPPLY and RESERVE_COLLATERAL_MINT are read directly from the cloned reserve account data using their known byte offsets within the Reserve struct:

Hijacking the USDC mint:

Because the cloned mainnet USDC mint has a fixed mint authority (controlled by Circle), the test must override the authority to enable minting test tokens. This is done via Surfpool's surfnet_setAccount JSON-RPC method, which allows arbitrary account state to be injected into the test validator. The mint authority field is overwritten in-memory with the operator's public key and pushed back:

Resetting the reserve's stale slot counter:

Kamino's deposit_reserve_liquidity instruction performs a freshness check because if the reserve has not been refreshed within the current slot, the deposit is rejected. Since the cloned reserve reflects a past mainnet state, this check would always fail in a test environment. The last updated slot counter at byte offset 16 in the reserve data is zeroed out before the tests run, bypassing this check:

Test Cases

Running the Contract

Build

anchor build

Start the local test validator (Surfpool)

surfpool --start

Run Tests

anchor test --skip-local-validator

On some WSL setups, the deploy path inside anchor test can be slower or unreliable relative to Surfpool's blockhash expiry window, which may cause Blockhash not found / Blockhash expired errors. In that case, deploy explicitly first, then run tests without redeploying:

Deploy

solana program deploy target/deploy/anchor_payroll_capstone_q1_26.so\
  --program-id target/deploy/anchor_payroll_capstone_q1_26-keypair.json\
  -u localhost\
  --use-rpc

This command talks directly to the local validator's JSON‑RPC on localhost:8899, avoiding the extra orchestration overhead of anchor test during deployment and making it less likely the blockhash expires mid‑upload.

Run Tests

anchor test --skip-local-validator --skip-deploy

This runs the tests against your already‑deployed program and skips the deploy step entirely.

Atlas Payroll was built as a Q1 2026 capstone project. The contract targets Solana mainnet-beta, with the Kamino Finance USDC lending market (KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD) as the yield source. Full source code: github.com/DivineUX23/anchor-payroll-capstone-q1-26

Part 7: Interacting with ERC-721 NFTs using `web3.py`

Divine Igbinoba — Wed, 06 Aug 2025 19:50:42 +0000

Previously, we established the critical role of blockchain standards and then learned how to interact with fungible (ERC-20) tokens.

Today, we're shifting our focus to the other side of the coin: non-fungible tokens (NFTs) and their primary standard, ERC-721.

What is an ERC-721 NFT?

An ERC-721 token is a standard for unique, indivisible digital assets on the Ethereum blockchain.

Unlike an ERC-20 token, where every unit is identical (1 Pi is the same as another 1 Pi), each ERC-721 token is unique and has its own distinct properties - They are not interchangeable.

Think of it like a ticket; While you might have a ticket to the same show as someone else, your ticket has a unique seat number, making it fundamentally different.

The key to an ERC-721 token's uniqueness is its tokenId, a unique identifier (usually a uint256 integer) that separates it from all other tokens in the same contract.

This is what makes them ideal for representing digital art, collectables, in-game items, and even real-world assets like property deeds.

Key ERC-721 Functions We'll Use:

While the full standard is extensive, we'll focus on these core functions that allow us to interact with NFTs:

Read Functions (View):

name() & symbol(): Returns the name and symbol of the NFT collection (e.g., "CryptoKitties", "CK").

2. balanceOf(address owner): Returns the number of NFTs an address owns in this collection.

3. ownerOf(uint256 tokenId): A fundamental function that returns the address of the current owner of a specific tokenId.

4. tokenURI(uint256 tokenId): Returns a URI (Uniform Resource Identifier) pointing to a JSON file containing the NFT's metadata (e.g., name, description, image, and other attributes).

This is how an NFT's unique data is linked to its on-chain token.

Write Functions (State-Changing):

1. transferFrom(address from, address to, uint256 tokenId): Transfers a specific NFT from one address to another. This is the function you use to sell or gift an NFT.

2. mint(address recipient): Create new tokens (custom function, not in standard)

Hands-On: Deploying and Minting Your Own ERC-721

Let's deploy a simple NFT contract to Ganache. This contract will be a basic ERC-721 implementation with a simple function to mint new tokens.

Here's the Solidity code for our SimpleNFT. It's a simplified version of the standard for clarity:

pragma solidity ^0.8.0;

contract SimpleNFT {
    string public name = "Very Simple NFT";
    string public symbol = "VSNFT";
    uint256 private _nextTokenId;

    // Mapping
    mapping(uint256 => address) private _owners;
    mapping(address => uint256) private _balances;
    mapping(uint256 => string) private _tokenURIs;

    // ERC-721 Events
    event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);


    // --- View Functions (read-only) ---
    function balanceOf(address owner) public view returns (uint256) {
        require(owner != address(0), "Address zero is not a valid owner");
        return _balances[owner];
    }
    function ownerOf(uint256 tokenId) public view returns (address) {
        address owner = _owners[tokenId];
        require(owner != address(0), "Token ID does not exist");
        return owner;
    }
    function tokenURI(uint256 tokenId) public view returns (string memory) {
        return _tokenURIs[tokenId];
    }

    // --- State-Changing Functions (Transactions) --
    // mint a new token to an address
    function mint(address recipient) public returns (uint256) {
        uint256 newTokenId = _nextTokenId;
        require(recipient != address(0), "Cannot mint to the zero address");

        // set owner and increment balance
        _owners[newTokenId] = recipient;
        _balances[recipient] += 1;
        _nextTokenId++;

        // set a dummy metadata URI
        _tokenURIs[newTokenId] = string(abi.encodePacked("https://your.website/metadata/", _nextTokenId - 1));

        // emit the Transfer event (from null address to recipient for mint)
        emit Transfer(address(0), recipient, newTokenId);
        return newTokenId;
    }

    // transfer tokens
    function transferFrom(address from, address to, uint256 tokenId) public {
        require(ownerOf(tokenId) == from, "Sender is not the owner of the token");
        require(to != address(0), "Cannot transfer to the zero address");

        // this is a simplified transfer; a full ERC-721 implementation would check for approvals
        _balances[from] -= 1;
        _balances[to] += 1;
        _owners[tokenId] = to;
        emit Transfer(from, to, tokenId);
    }
}

NOTE: This is a simplified ERC-721 implementation for learning purposes afull implementation would use libraries like OpenZeppelin.

Deployment Steps (using Remix IDE to Ganache):

Follow the detailed steps from Part 2: Deploying Your First Smart Contract for deploying a contract to Ganache, but with these specifics:

Paste the **SimpleNFT.sol** code into a new file in Remix (e.g., SimpleNFT.sol).
Compile it, remember to select paris as EVM Version.
Go to the "Deploy & Run Transactions" tab, ensure "DEV-GANACHE PROVIDER" is selected.
Click the orange "Deploy" button.
After deployment, your contract will appear in the "Deployed Contracts" list. Expand it.
Copy the **CONTRACT_ADDRESS** and the updated **CONTRACT_ABI** from the deployed contract section.

Interacting with Your NFT using `web3.py`

Now, let's update our Python script to interact with your newly minted NFT.

Update your Python script:


import os
import json
from web3 import Web3, HTTPProvider
from web3.middleware import ExtraDataToPOAMiddleware
from eth_account import Account
from dotenv import load_dotenv

load_dotenv()

RPC_URL = os.getenv("RPC_URL")
PRIVATE_KEY = os.getenv("GANACHE_PRIVATE_KEY")

if not RPC_URL or not PRIVATE_KEY:
    raise ValueError("RPC_URL or GANACHE_PRIVATE_KEY not found in .env file.")

try:
    w3 = Web3(HTTPProvider(RPC_URL))
    w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)

    if not w3.is_connected():
        print(f"❌ Failed to connect to Ethereum node at {RPC_URL}")
        exit()
    print(f"✅ Successfully connected to Ethereum node at {RPC_URL}")

    sender_account = Account.from_key(PRIVATE_KEY)
    print(f"\n🔑 Sender Account Address: {sender_account.address}")
    print(f"💰 Sender ETH Balance: {w3.from_wei(w3.eth.get_balance(sender_account.address), 'ether')} ETH")

    # --- ERC-721 NFT Interaction ---

    # IMPORTANT: replace with your NEWLY deployed SimpleNFT contract address and ABI Get these values after deploying SimpleNFT.sol in Remix
    ERC721_CONTRACT_ADDRESS = "0x85Bf1249EAf7b25a6Eae6F61ecaCDcBC4fCB8eCa"
    ERC721_CONTRACT_ABI = json.loads('''
[
    {
        "inputs": [],
        "stateMutability": "nonpayable",
        "type": "constructor"
    },
    {
        "anonymous": false,
        "inputs": [
            {"indexed": true, "internalType": "address", "name": "from", "type": "address"},
            {"indexed": true, "internalType": "address", "name": "to", "type": "address"},
            {"indexed": true, "internalType": "uint256", "name": "tokenId", "type": "uint256"}
        ],
        "name": "Transfer",
        "type": "event"
    },
    {
        "inputs": [
            {"internalType": "address", "name": "owner", "type": "address"}
        ],
        "name": "balanceOf",
        "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [
            {"internalType": "address", "name": "recipient", "type": "address"}
        ],
        "name": "mint",
        "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
        "stateMutability": "nonpayable",
        "type": "function"
    },
    {
        "inputs": [],
        "name": "name",
        "outputs": [{"internalType": "string", "name": "", "type": "string"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [
            {"internalType": "uint256", "name": "tokenId", "type": "uint256"}
        ],
        "name": "ownerOf",
        "outputs": [{"internalType": "address", "name": "", "type": "address"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [],
        "name": "symbol",
        "outputs": [{"internalType": "string", "name": "", "type": "string"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [
            {"internalType": "uint256", "name": "tokenId", "type": "uint256"}
        ],
        "name": "tokenURI",
        "outputs": [{"internalType": "string", "name": "", "type": "string"}],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [
            {"internalType": "address", "name": "from", "type": "address"},
            {"internalType": "address", "name": "to", "type": "address"},
            {"internalType": "uint256", "name": "tokenId", "type": "uint256"}
        ],
        "name": "transferFrom",
        "outputs": [],
        "stateMutability": "nonpayable",
        "type": "function"
    }
]
    ''') # replace this entire string with your copied, UPDATED ABI

    # create the ERC-721 contract instance
    nft_contract = w3.eth.contract(address=ERC721_CONTRACT_ADDRESS, abi=ERC721_CONTRACT_ABI)

    print(f"✅ ERC-721 contract loaded successfully at address: {ERC721_CONTRACT_ADDRESS}")

    # --- 1. Read NFT Information ---
    collection_name = nft_contract.functions.name().call()
    collection_symbol = nft_contract.functions.symbol().call()
    sender_nft_balance = nft_contract.functions.balanceOf(sender_account.address).call()

    print(f"\nℹ️ Collection Name: {collection_name} ({collection_symbol})")
    print(f"💰 {sender_account.address} owns {sender_nft_balance} {collection_symbol} NFT(s).")


    # --- 2. MINT the NFT ---

    print(f"\n➡️ Attempting to mint Token from to {sender_account.address}...")

    # build the 'mint' transaction
    nonce = w3.eth.get_transaction_count(sender_account.address)

    transfer_txn = nft_contract.functions.mint(
        sender_account.address,  # recipient
    ).build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 200000,
        'gasPrice': w3.eth.gas_price
    })

    # sign and send the transaction
    signed_txn = w3.eth.account.sign_transaction(transfer_txn, private_key=PRIVATE_KEY)
    tx_hash = w3.eth.send_raw_transaction(signed_txn.raw_transaction)
    print(f"🚀 Transfer transaction sent! Hash: {tx_hash.hex()}")

    # wait for the transaction to be mined
    tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

    if tx_receipt['status'] == 1:
        print("🎉 NFT minting successful!")

        # verify new balances
        new_balance = nft_contract.functions.balanceOf(sender_account.address).call()
        print(f"💰 new balance ({sender_account.address}): {new_balance} {collection_symbol} NFT(s)")
    else:
        print(f"❌ Mint failed! Transaction receipt: \n {tx_receipt}")

    # Let's interact with our first minted token, which has tokenId 0
    token_id = 0

    try:
        # get the owner of the specific token
        owner_of_token = nft_contract.functions.ownerOf(token_id).call()
        print(f"👑 owner of Token #{token_id} is: {owner_of_token}")

        # get the metadata URI for the token
        token_uri = nft_contract.functions.tokenURI(token_id).call()
        print(f"🔗 metadata URI for Token #{token_id}: {token_uri}")

    except Exception as e:
        print(f"❌ Error getting owner or URI for Token #{token_id}: {e}")

    # --- 3. Transfer the NFT ---
    # get a recipient address from Ganache (e.g., the second account)
    if "127.0.0.1" in RPC_URL.lower() and len(w3.eth.accounts) > 1:
        recipient_address = w3.eth.accounts[1]
    else:
        recipient_address = "0xEnterSecondAddress"

    print(f"\n\n➡️ Attempting to transfer Token #{token_id} from {sender_account.address} to {recipient_address}...")

    # build the 'transferFrom' transaction
    nonce = w3.eth.get_transaction_count(sender_account.address)

    transfer_txn = nft_contract.functions.transferFrom(
        sender_account.address, # from
        recipient_address,      # to
        token_id                # tokenId
    ).build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 200000,
        'gasPrice': w3.eth.gas_price
    })

    # sign and send the transaction
    signed_txn = w3.eth.account.sign_transaction(transfer_txn, private_key=PRIVATE_KEY)
    tx_hash = w3.eth.send_raw_transaction(signed_txn.raw_transaction)
    print(f"\n🚀 Transfer transaction sent! Hash: {tx_hash.hex()}")

    # wait for the transaction to be mined
    tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

    if tx_receipt['status'] == 1:
        print("\n🎉 NFT transfer successful!")

        # verify the new ownership
        new_owner = nft_contract.functions.ownerOf(token_id).call()
        print(f"\n👑 new owner of Token #{token_id} is now: {new_owner}")

        # verify new balances
        sender_new_balance = nft_contract.functions.balanceOf(sender_account.address).call()
        recipient_new_balance = nft_contract.functions.balanceOf(recipient_address).call()
        print(f"\n\n 💰 new balance of sender ({sender_account.address}): {sender_new_balance} {collection_symbol} NFT(s)")
        print(f"\n 💰 new balance of recipient ({recipient_address}): {recipient_new_balance} {collection_symbol} NFT(s)")
    else:
        print("❌ Transfer failed! Transaction receipt:")
        print(tx_receipt)

except Exception as e:
    print(f"An error occurred: {e}")
    print("\nensure your ERC721_CONTRACT_ADDRESS and ERC721_CONTRACT_ABI are correct and match your newly deployed token.")
    print("also, ensure your Ganache is running with the correct RPC URL and private key, and that you have minted at least one token.")

print("\n--- End of ERC-721 Interaction ---")

After executing your script, you should see something like this:

NOTE: In a real-world scenario, the tokenURI would link to a decentralised storage solution like IPFS,

the tokenURI function should return a link to JSON metadata following this structure:

{
  "name": "Very Simple NFT #1",
  "description": "This is a unique digital collectible",
  "image": "https://ipfs.io/ipfs/QmHash...",
  "attributes": [
    {
      "trait_type": "Color",
      "value": "Blue"
    },
    {
      "trait_type": "Rarity",
      "value": "Legendary"
    }
  ]
}

What You've Accomplished

You've successfully bridged the gap from fungible tokens to unique digital assets. You now know how to:

Distinguish between fungible (ERC-20) and non-fungible (ERC-721) tokens.
Deploy your own simple ERC-721 NFT contract.
Use web3.py to:
Query NFT metadata and ownership details like name(), symbol(), balanceOf(), and ownerOf().
Mint new unique tokens on-chain.
Execute a transferFrom transaction to move ownership of a specific NFT.

This is the core of how NFT marketplaces and games function under the hood.

Resources for Continued Learning:

OpenZeppelin ERC-721 Docs - Production-ready implementations
ERC-721 Standard -Official specification
NFT Metadata Standards - Industry best practices
IPFS Documentation - Decentralised storage for NFT metadata

Questions about NFT implementation or encountered any issues? Drop a comment below

Part 6: ERC-20 Tokens with web3.py - Balances, Transfers, and Approvals

Divine Igbinoba — Tue, 29 Jul 2025 00:08:16 +0000

In our previous post, we explored the crucial role of blockchain standards in enabling interoperability and composability within the decentralized ecosystem.

We learned that standards like ERC-20 provide a common language for smart contracts and applications to interact seamlessly.

Today, we're putting that understanding into practice by diving deep into the most widely adopted token standard on Ethereum: ERC-20 tokens.

If you've ever held cryptocurrencies like USDC, DAI, UNI, or even wrapped Bitcoin (WBTC) on Ethereum, you've interacted with ERC-20 tokens.

What Are ERC-20 Tokens? The Foundation of Digital Assets

An ERC-20 token is a standard for fungible (interchangeable) tokens on the Ethereum blockchain. "Fungible" means each unit of the token is identical to any other unit,

Just like one dollar note is interchangeable with another, or one Bitcoin is interchangeable with another Bitcoin.

This standard defines a common set of rules and functions that any compliant token contract must implement.

This standardization enables:

Universal wallet support for displaying any ERC-20 token balance
Seamless Decentralized Exchanges (DEXs) trading between different ERC-20 tokens
DeFi protocol integration accepting various tokens as collateral
Cross-platform compatibility across thousands of applications

Key ERC-20 Functions We'll Explore

The ERC-20 standard specifies several core functions.

We'll focus on the most commonly used ones for reading balances and making transfers, including the critical approve and transferFrom pattern used by dApps:

Read Functions (View State)

1.**totalSupply()** - Returns the total number of tokens in existence.

2. **balanceOf(address)** - Returns the token balance of a specific address.

3.**allowance(owner, spender)** - Returns the amount of tokens that an owner has allowed a spender to withdraw.

Write Functions (Change State)

**transfer(recipient, amount)** - Transfers tokens directly from the message sender (the account initiating the transaction) to a recipient.

2. **approve(spender, amount)** - Allows a "spender" (another contract or address, often a dApp) to withdraw a specified amount of tokens from the sender's account.

3. **transferFrom(sender, recipient, amount)** - Transfers tokens from one address (sender) to another (recipient) on behalf of the sender.

This function can only be called by a spender who has received prior approval from the sender.

Building Your Own ERC-20 Token

To practice interacting with an ERC-20 token, we'll deploy a simple one to our local Ganache blockchain using Remix,

just like we did with our Counter contract. This will give you full control over your own test tokens.

Here's our production-ready SimpleERC20 contract:

// SimpleERC20.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract SimpleERC20 {
    // Token metadata
    string public name = "My Test Token";
    string public symbol = "MTT";
    uint8 public decimals = 18; // Standard precision (like ETH)
    uint256 public totalSupply;
    // Core mappings for token accounting
    mapping(address => uint256) public balanceOf;
    mapping(address => mapping(address => uint256)) public allowance;
    // Events for blockchain logging and dApp integration
    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
    // Constructor: Initialize token supply
    constructor(uint256 initialSupply) {
        totalSupply = initialSupply * 10**decimals; // Convert to wei-like units
        balanceOf[msg.sender] = totalSupply; // Assign all tokens to deployer
        emit Transfer(address(0), msg.sender, totalSupply);
    }
    // Direct token transfer
    function transfer(address _to, uint256 _value) public returns (bool) {
        require(_to != address(0), "SimpleERC20: Transfer to zero address");
        require(balanceOf[msg.sender] >= _value, "SimpleERC20: Insufficient balance");

        balanceOf[msg.sender] -= _value;
        balanceOf[_to] += _value;
        emit Transfer(msg.sender, _to, _value);
        return true;
    }
    // Approve spender allowance
    function approve(address _spender, uint256 _value) public returns (bool) {
        require(_spender != address(0), "SimpleERC20: Approve to zero address");

        allowance[msg.sender][_spender] = _value;
        emit Approval(msg.sender, _spender, _value);
        return true;
    }
    // Third-party transfer (requires prior approval)
    function transferFrom(address _from, address _to, uint256 _value) public returns (bool) {
        require(_from != address(0), "SimpleERC20: Transfer from zero address");
        require(_to != address(0), "SimpleERC20: Transfer to zero address");
        require(balanceOf[_from] >= _value, "SimpleERC20: Insufficient balance");
        require(allowance[_from][msg.sender] >= _value, "SimpleERC20: Allowance exceeded");
        balanceOf[_from] -= _value;
        balanceOf[_to] += _value;
        allowance[_from][msg.sender] -= _value;
        emit Transfer(_from, _to, _value);
        return true;
    }
}

Deployment Steps (using Remix IDE to Ganache):

Follow the detailed steps from Part 2: Deploying Your First Smart Contract for deploying a contract to Ganache, but with these specifics:

Paste the **SimpleERC20.sol** code into a new file in Remix (e.g., SimpleERC20.sol).

2. Compile it (ensure EVM version 'Paris').

3. Go to the "Deploy & Run Transactions" tab.

4. Ensure "DEV - GANACHE PROVIDER" is selected and connected.

Before clicking "Deploy":

Next to the "Deploy" button, you'll see a field for the constructor arguments. Our SimpleERC20 constructor takes initialSupply as a uint256.
Enter a large number here for the initial supply, e.g., 1000000000000000000000000 (which is 1,000,000 tokens with 18 decimals, or 106 * 10^18 Wei-like units).

6. Click the orange "Deploy" button and confirm the MetaMask transaction.

7. Crucially, copy the NEW **CONTRACT_ADDRESS** and the updated **CONTRACT_ABI** from the deployed contract section.

Interacting with Your ERC-20 Token using `web3.py`

Now, let's modify our app.py script to interact with your newly deployed SimpleERC20 token.


import os
import json
from web3 import Web3, HTTPProvider
from web3.middleware import ExtraDataToPOAMiddleware
from eth_account import Account
from dotenv import load_dotenv

load_dotenv()

RPC_URL = os.getenv("RPC_URL")
PRIVATE_KEY = os.getenv("GANACHE_PRIVATE_KEY")

if not RPC_URL or not PRIVATE_KEY:
    raise ValueError("RPC_URL or GANACHE_PRIVATE_KEY not found in .env file.")

try:
    w3 = Web3(HTTPProvider(RPC_URL))
    w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)

    if not w3.is_connected():
        print(f"❌ Failed to connect to Ethereum node at {RPC_URL}")
        exit()
    print(f"✅ Successfully connected to Ethereum node at {RPC_URL}")

    sender_account = Account.from_key(PRIVATE_KEY)
    print(f"\n🔑 Sender Account Address: {sender_account.address}")
    # Note: This is your ETH balance, not token balance. You need ETH for gas!
    print(f"💰 Sender ETH Balance: {w3.from_wei(w3.eth.get_balance(sender_account.address), 'ether')} ETH")

    # --- ERC-20 Token Interaction ---

    print("\n--- ERC-20 Token Interaction ---")

    # IMPORTANT: Replace with your NEWLY deployed SimpleERC20 contract address and ABI
    # Get these values after deploying SimpleERC20.sol in Remix
    ERC20_CONTRACT_ADDRESS = "0x6213A6c50505ebCA6391d002876Af1c70168830a" # e.g., "0x5FbDB2315678afecb367f032d93F642f64180aa3"

    ERC20_CONTRACT_ABI = json.loads('''
[
    {
        "constant": true,
        "inputs": [],
        "name": "name",
        "outputs": [{"name": "", "type": "string"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "constant": false,
        "inputs": [{"name": "_spender", "type": "address"}, {"name": "_value", "type": "uint256"}],
        "name": "approve",
        "outputs": [{"name": "", "type": "bool"}],
        "payable": false, "stateMutability": "nonpayable", "type": "function"
    },
    {
        "constant": true,
        "inputs": [],
        "name": "totalSupply",
        "outputs": [{"name": "", "type": "uint256"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "constant": false,
        "inputs": [{"name": "_from", "type": "address"}, {"name": "_to", "type": "address"}, {"name": "_value", "type": "uint256"}],
        "name": "transferFrom",
        "outputs": [{"name": "", "type": "bool"}],
        "payable": false, "stateMutability": "nonpayable", "type": "function"
    },
    {
        "constant": true,
        "inputs": [],
        "name": "decimals",
        "outputs": [{"name": "", "type": "uint8"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "constant": true,
        "inputs": [{"name": "_owner", "type": "address"}],
        "name": "balanceOf",
        "outputs": [{"name": "balance", "type": "uint256"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "constant": true,
        "inputs": [],
        "name": "symbol",
        "outputs": [{"name": "", "type": "string"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "constant": false,
        "inputs": [{"name": "_to", "type": "address"}, {"name": "_value", "type": "uint256"}],
        "name": "transfer",
        "outputs": [{"name": "", "type": "bool"}],
        "payable": false, "stateMutability": "nonpayable", "type": "function"
    },
    {
        "constant": true,
        "inputs": [{"name": "_owner", "type": "address"}, {"name": "_spender", "type": "address"}],
        "name": "allowance",
        "outputs": [{"name": "", "type": "uint256"}],
        "payable": false, "stateMutability": "view", "type": "function"
    },
    {
        "inputs": [{"internalType": "uint256", "name": "initialSupply", "type": "uint256"}],
        "payable": false, "stateMutability": "nonpayable", "type": "constructor"
    },
    {
        "anonymous": false,
        "inputs": [{"indexed": true, "name": "from", "type": "address"}, {"indexed": true, "name": "to", "type": "address"}, {"indexed": false, "name": "value", "type": "uint256"}],
        "name": "Transfer", "type": "event"
    },
    {
        "anonymous": false,
        "inputs": [{"indexed": true, "name": "owner", "type": "address"}, {"indexed": true, "name": "spender", "type": "address"}, {"indexed": false, "name": "value", "type": "uint256"}],
        "name": "Approval", "type": "event"
    }
]
''') # IMPORTANT: Replace this entire multi-line string with your copied, UPDATED ABI

    # Create the ERC-20 contract instance
    token_contract = w3.eth.contract(address=ERC20_CONTRACT_ADDRESS, abi=ERC20_CONTRACT_ABI)

    print(f"✅ ERC-20 Token contract loaded successfully at address: {ERC20_CONTRACT_ADDRESS}")

    # -- 1. Read Token Information ---
    token_name = token_contract.functions.name().call()
    token_symbol = token_contract.functions.symbol().call()
    token_decimals = token_contract.functions.decimals().call()
    token_total_supply_raw = token_contract.functions.totalSupply().call()

    # Convert total supply to human-readable format
    # Note: Tokens have 'decimals', similar to how ETH has 18 decimal places (Wei)
    token_total_supply = token_total_supply_raw / (10**token_decimals)

    print(f"\nℹ️ Token Name: {token_name} ({token_symbol})")
    print(f"ℹ️ Token Decimals: {token_decimals}")
    print(f"ℹ️ Total Supply (Raw): {token_total_supply_raw}")
    print(f"ℹ️ Total Supply ({token_symbol}): {token_total_supply}")

    # Get balance of the sender (deployer) account
    sender_token_balance_raw = token_contract.functions.balanceOf(sender_account.address).call()
    sender_token_balance = sender_token_balance_raw / (10**token_decimals)
    print(f"💰 {token_symbol} Balance of {sender_account.address}: {sender_token_balance} {token_symbol}")

    # --- 2. Transfer Tokens (using `transfer` function) ---
    # Get a recipient address from Ganache (e.g., the second account)
    if "127.0.0.1" in RPC_URL.lower() and len(w3.eth.accounts) > 1:
        recipient_address = w3.eth.accounts[1]
    else:
        # Fallback if not Ganache or not enough accounts
        # Use a random address for demonstration if Ganache accounts are not available
        recipient_address = "0x789F8a60F25e3d7F6A8B08A4E9A4B8C1D6E5F4A3"

    transfer_amount_human = 10 # Transfer 10 tokens
    # Convert human-readable amount to raw token units (accounting for decimals)
    transfer_amount_raw = int(transfer_amount_human * (10**token_decimals))

    print(f"\n➡️ Attempting to transfer {transfer_amount_human} {token_symbol} to {recipient_address}...")

    # Get the current nonce for the sender. Nonce prevents replay attacks.
    nonce = w3.eth.get_transaction_count(sender_account.address)

    # Build the 'transfer' transaction. This creates the transaction object.
    transfer_txn = token_contract.functions.transfer(
        recipient_address,
        transfer_amount_raw
    ).build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 200000, # Set a reasonable gas limit for the transaction
        'gasPrice': w3.eth.gas_price # Get current gas price from the network
    })

    # Sign the transaction with the sender's private key
    signed_txn = w3.eth.account.sign_transaction(transfer_txn, private_key=PRIVATE_KEY)
    # Send the signed raw transaction to the network
    tx_hash = w3.eth.send_raw_transaction(signed_txn.raw_transaction)
    print(f"🚀 Transfer transaction sent! Hash: {tx_hash.hex()}")

    # Wait for the transaction to be mined and get the receipt
    tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

    if tx_receipt['status'] == 1:
        print("🎉 Transfer successful!")
        # Verify new balances after transfer
        new_sender_balance_raw = token_contract.functions.balanceOf(sender_account.address).call()
        new_recipient_balance_raw = token_contract.functions.balanceOf(recipient_address).call()
        print(f"💰 New {token_symbol} Balance of {sender_account.address}: {new_sender_balance_raw / (10**token_decimals)} {token_symbol}")
        print(f"💰 New {token_symbol} Balance of {recipient_address}: {new_recipient_balance_raw / (10**token_decimals)} {token_symbol}")
    else:
        print("❌ Transfer failed! Transaction receipt:")
        print(tx_receipt)

    # --- 3. Approve and TransferFrom (for dApp interaction) ---
    # This pattern is used when a dApp needs to move tokens on your behalf (e.g., in a DEX, you 'approve' the DEX contract to spend your tokens, then the DEX calls transferFrom).

    # Let's use the third Ganache account as our 'spender' for demonstration.
    if "127.0.0.1" in RPC_URL.lower() and len(w3.eth.accounts) > 2:
        spender_address = w3.eth.accounts[2]
    else:
        # Another random address if Ganache accounts are not available
        spender_address = "0x89C6F7D8A7F4B2C6F9C7D6E5F4A3B8C1D6E5F4A3"

    approve_amount_human = 5 # Allow the spender to move 5 tokens
    approve_amount_raw = int(approve_amount_human * (10**token_decimals))

    print(f"\n➡️ Approving {spender_address} to spend {approve_amount_human} {token_symbol} from {sender_account.address}...")

    # Get nonce for the approval transaction
    nonce = w3.eth.get_transaction_count(sender_account.address)

    # Build the 'approve' transaction
    approve_txn = token_contract.functions.approve(
        spender_address,
        approve_amount_raw
    ).build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 100000, # Gas for approve is typically less than transfer
        'gasPrice': w3.eth.gas_price
    })

    # Sign and send the approve transaction
    signed_approve_txn = w3.eth.account.sign_transaction(approve_txn, private_key=PRIVATE_KEY)
    approve_tx_hash = w3.eth.send_raw_transaction(signed_approve_txn.raw_transaction)
    print(f"🚀 Approve transaction sent! Hash: {approve_tx_hash.hex()}")

    # Wait for approve transaction to be mined
    print("⏳ Waiting for approve transaction to be mined...")
    approve_tx_receipt = w3.eth.wait_for_transaction_receipt(approve_tx_hash)

    if approve_tx_receipt['status'] == 1:
        print("🎉 Approve successful!")
        # Verify allowance
        current_allowance_raw = token_contract.functions.allowance(sender_account.address, spender_address).call()
        print(f"💰 Current Allowance for {spender_address} on {sender_account.address}: {current_allowance_raw / (10**token_decimals)} {token_symbol}")

    else:
        print("❌ Approve failed! Transaction receipt:")
        print(approve_tx_receipt)

except Exception as e:
    print(f"An error occurred: {e}")
    print("\nEnsure your ERC20_CONTRACT_ADDRESS and ERC20_CONTRACT_ABI are correct and match your newly deployed token.")
    print("Also, ensure your Ganache is running with the correct RPC URL and private key, and that the sender account has enough ETH for gas.")

You'll see output detailing:

The token's basic information (name, symbol, decimals, total supply).

2. Your initial token balance (the deployer account will have the entire initial supply).

3. A transfer transaction, showing tokens moving from your account to a recipient account on Ganache.

4. An approve transaction, granting a "spender" address permission to move a certain amount of your tokens.

5. Verification of the allowance set.

You'd see something like this

Here is an integration workflow to give you a clear picture of how the ERC-20 standard powers foundational DeFi use cases

For DEX Integration Flow (e.g. Uniswap):

User Calls approve(dex_address, amount)

The user allows the DEX smart contract to withdraw a set amount of their ERC-20 tokens.
This is done via the approve function of the token contract.

2. DEX Calls transferFrom(user, dex_pool, amount)

The DEX uses transferFrom to move tokens from the user's wallet into the liquidity pool.
This only works because the user previously approved the DEX to do this.

3. Trade Executes Atomically

Using the pool reserves, the DEX swaps the user's tokens for another (e.g. USDC → DAI).
Everything happens in one atomic transaction, so it either succeeds or fails as a whole.

The uniform ERC-20 interface lets the DEX handle any compliant token without custom logic.

What You've Accomplished

You've just gained a superpower in Web3 development! You now know how to:

Understand the fundamental ERC-20 token standard and its importance.

2. Deploy your own custom ERC-20 token for testing.

3. Use web3.py to:

Query token details like name, symbol, decimals, and totalSupply.
Check balanceOf any address.
Perform transfer transactions, directly sending tokens.
Set approve allowances for other addresses/contracts, a critical step for dApp interactions.
Check allowance amounts.

Useful Resources:

OpenZeppelin ERC-20 Implementation --- Production-ready contracts
EIP-20 Specification --- Official ERC-20 standard
Token Lists --- Discover existing ERC-20 tokens

Follow for more blockchain development tutorials and share your token creations in the comments! 🚀

Having issues with your implementation? Drop your error messages below and I'll help you debug!

Part 5: The Backbone of Blockchain Interoperability - Understanding Standards

Divine Igbinoba — Mon, 21 Jul 2025 18:37:47 +0000

How standardized protocols enable seamless interaction between wallets, dApps, and smart contracts

So far, you've learned the practical skills of blockchain interaction: reading data, sending transactions, and listening for events.

You've even deployed your own Counter contract and successfully modified blockchain state.

But as you venture deeper into decentralized applications (dApps), you'll constantly encounter terms like ERC-20, ERC-721, EIP, and interfaces.

What are these mysterious acronyms, and why are they absolutely crucial for blockchain development?

Today, we're zooming out to understand the fundamental concept that makes the blockchain ecosystem so powerful and interconnected: Blockchain Standards.

What Are Blockchain Standards?

Blockchain standards are agreed-upon sets of rules, conventions, or interfaces that smart contracts and applications adhere to.

They define how certain types of digital assets or functionalities should behave on a blockchain.

Now, imagine if every device manufacturer created their own unique electrical outlet.

You'd need a different adapter for every appliance! Instead, we have standardized plugs and outlets that work universally.

Blockchain Standards Work Similarly...

If every token had its own unique way of handling transfers or checking balances:

❌ No wallet could support multiple tokens
❌ No decentralized exchange could trade them
❌ dApps couldn't interact with each other
❌ Users would need different interfaces for every token

Standards solve this by providing universal interfaces for common functionalities.

Why Standards Are Essential for Blockchain

Standards aren't just helpful, they're absolutely vital for the growth and utility of any blockchain ecosystem for the following:

1. Interoperability: The Foundation of DeFi

Standards ensure different smart contracts, wallets, exchanges, and dApps can seamlessly interact with each other.

Example: Because all ERC-20 tokens implement the same *transfer()* function, MetaMask can send any ERC-20 token, and Uniswap can swap any pair of ERC-20 tokens without custom integration for each one.

2. Composability: "Money Legos"

Standards enable composability, the ability to combine different dApps and protocols like LEGO bricks to build complex applications.

This is the secret sauce behind DeFi innovation.

Example DeFi Flow:

Deposit USDC into Compound (lending protocol)\
Receive cUSDC (interest-bearing tokens)\
Use cUSDC as collateral on MakerDAO\
Mint DAI stablecoins\
Trade DAI for ETH on Uniswap\
Stake ETH in Ethereum 2.0

This entire flow is possible because each protocol adheres to token standards!

3. Developer Efficiency

Developers don't reinvent the wheel for common functionalities. They use:

Well-tested implementations: Reduced bugs and security risks
Audited standard code: Battle-tested by the community
Proven patterns: Faster development cycles

4. Superior User Experience

Standards mean familiarity for users:

If you know how to send one ERC-20 token, you know how to send them all
Wallets have consistent interfaces across different tokens
Reduced learning curve for new dApps

5. Ecosystem Growth Acceleration

By lowering barriers for both developers and users, standards:

Accelerate innovation
Increase adoption
Enable network effects
Foster creative combinations

How Are Blockchain Standards Created?

On Ethereum, standards originate as Ethereum Improvement Proposals (EIPs) through a democratic, open process:

The EIP Process

Proposal: Anyone can submit an EIP describing a new feature or standard
Discussion: Community review and feedback on GitHub and forums
Refinement: Authors iterate based on feedback
Review: Technical review by EIP editors
Final: Community consensus and implementation

EIP Categories

Core EIPs: Protocol-level changes (consensus, networking)

Networking EIPs: DevP2P protocol improvements

Interface EIPs: API/RPC specifications

ERC EIPs: Application-level standards (our focus!)

What is ERC?

ERC stands for Ethereum Request for Comments. They define standard interfaces that ensure interoperability between dApps, wallets, and tokens.

Essential Blockchain Standard Categories

1. Token Standards

Define how different digital assets behave:

🪙 ERC-20 (Fungible Tokens)

Use Case: Currencies, utility tokens, stablecoins
Examples: DAI, USDC, LINK, UNI
Key Feature: Every unit is identical and interchangeable
Functions: transfer(), balanceOf(), approve()

🎨 ERC-721 (Non-Fungible Tokens)

Use Case: Digital art, collectibles, domain names
Examples: CryptoPunks, Bored Ape Yacht Club, ENS domains
Key Feature: Each token has a unique ID and properties
Functions: ownerOf(), transferFrom(), tokenURI()

⚡ ERC-1155 (Multi-Token Standard)

Use Case: Gaming assets, complex applications
Examples: Gaming items, event tickets
Key Feature: Single contract manages multiple token types
Benefits: Gas efficiency, batch operations

2. Interface Standards

Enable standardized contract interaction:

🔍 EIP-165 (Interface Detection)

Purpose: Contracts declare which interfaces they support
Benefit: Other contracts can query capabilities dynamically
Example: Check if a contract supports ERC-721 before calling NFT functions

3. Identity & Naming Standards

🌐 ENS (Ethereum Name Service --- EIP-137)

Purpose: Human-readable names for blockchain addresses
Example: vitalik.eth → 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
Benefits: Improved UX, reduced errors, brandable addresses

4. Governance Standards

🗳️ EIP-2612 (Permit Extension for ERC-20)

Purpose: Gasless token approvals using signatures
Benefit: Better UX for dApp interactions
Use Case: Users can approve token spending without separate transactions

Standards in Action with web3.py

You've already benefited from standards in our previous tutorials! When you interact with smart contracts using:

contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=CONTRACT_ABI)

The ABI (Application Binary Interface) you provide is essentially web3.py's "map" to the contract's functions and events, which are often defined by standards.

ERC-20 Interaction Example

# Standard ERC-20 functions work across ALL ERC-20 tokens
erc20_abi = [...] # Standard ERC-20 ABI

# These functions work whether it's DAI, USDC, LINK, or any ERC-20 token
balance = contract.functions.balanceOf(user_address).call()
name = contract.functions.name().call()
symbol = contract.functions.symbol().call()
decimals = contract.functions.decimals().call()

# Transfer tokens (same function signature for all ERC-20s)
transfer_txn = contract.functions.transfer(to_address, amount).build_transaction({
    'from': sender_address,
    'nonce': nonce,
    'gas': 60000,
    'gasPrice': w3.eth.gas_price
})

This standardization means:

Wallet developers can support thousands of tokens with one implementation
DEX developers can create universal trading interfaces
Portfolio trackers can aggregate any ERC-20 tokens
You as a developer can build applications that work with any compliant token

Standards Enable Innovation

Some groundbreaking innovations made possible by standards:

🔄 Flash Loans (Aave, dYdX)

Borrow millions instantly, use in complex transactions, repay in same block
Only possible because of standardized token interfaces

🤖 Yield Farming (Compound, Yearn)

Automatically move funds between protocols to maximize returns
Requires standard interfaces for lending/borrowing protocols

📊 Portfolio Management (Zapper, DeBank)

Track assets across dozens of protocols in one interface
Possible because protocols follow standard patterns

⚡ MEV (Maximal Extractable Value)

Sophisticated trading strategies across multiple DEXs
Relies on predictable, standardized AMM interfaces

Common Misconceptions About Standards

❌ "Standards limit innovation" ✅ Standards provide foundations for innovation, like roads enable transportation

❌ "Standards are optional"✅ While technically optional, network effects make them practically essential

❌ "One standard fits all use cases" ✅ Different standards serve different needs (ERC-20 vs ERC-721 vs ERC-1155)

❌ "Standards never change" ✅ Standards evolve through new EIPs and extensions

Understanding blockchain standards is like learning the grammar of blockchain development.

It empowers you to build applications that aren't isolated islands but integral parts of a vast, interconnected ecosystem.

With this conceptual foundation, you're perfectly prepared for our next tutorial, where we'll put this knowledge into practice.

We'll dive deep into the most widely adopted token standard: ERC-20 tokens.

Key Takeaways

✅ Standards enable interoperability between different blockchain applications

✅ EIPs provide democratic governance for Ethereum standard development

✅ Token standards (ERC-20, ERC-721, ERC-1155) define asset behavior

✅ web3.py benefits from standards through consistent ABIs and functions

Resources for Further Learning

Ethereum Improvement Proposals (EIPs) - Official EIP repository
OpenZeppelin Contracts - Battle-tested standard implementations
Token Lists - Standardized token metadata

Found this deep dive helpful? 👏 Clap if you learnt something new. Share with fellow developers who need to understand blockchain standards.

Questions about specific standards or EIPs? Drop a comment, I love discussing the technical details that make blockchain ecosystems work! 💬

Part 4: Real-time Blockchain Updates --- Listening for Smart Contract Events with web3.py

Divine Igbinoba — Sun, 13 Jul 2025 20:44:12 +0000

Learn how to build responsive dApps that react instantly to blockchain changes using event listeners

In our previous posts (Part 1, Part 2, Part 3), you've mastered connecting to the blockchain, reading its data, and changing its state.

But what if you need to know immediately when something important happens on the blockchain?

How does your application get notified when our Counter increments, when a new NFT is minted, or when a swap occurs on a decentralized exchange?

Enter Smart Contract Events, the blockchain's built-in notification system.

Understanding Smart Contract Events

Smart contract events are like a built-in notification system for decentralized applications.

When a smart contract executes a function and reaches a specific point, it can "emit" an event. This event is then recorded in the transaction's log on the blockchain.

Why Events Are Powerful

🐛 Analytics & Debugging Events are useful for building analytics dashboards and debugging contract behavior.

⚡ Real-time Updates By "listening" for events, your application can react in real-time to changes happening on the blockchain, without constantly querying the contract's state.

Gas Efficiency: Events are much cheaper than storing data in contract storage, making them perfect for logging and notifications.

🔍 Off-chain Accessibility Events are specifically designed to be easily read and indexed by off-chain applications (like your web3.py script).

While you can inspect transaction data, parsing events is much more efficient and straightforward.

Now, imagine you're at a football match:

Reading (View Function): You glance up at the scoreboard to check the current score.
Sending a Transaction (Write Function): You're Messi, you strike, score a goal, and the scoreboard updates.
Emitting an Event: As soon as the ball hits the net, the stadium announcer bellows, "GOAL! Scored by Messi!" Everyone in the stadium hears it immediately.

Your web3.py script is like a fan in the stadium listening specifically for "GOAL!" announcements.

Updating Our Counter Contract with Events

Let's modify our Counter.sol contract to emit an event every time increment() or decrement() is called.

// Counter.sol (updated with Events)
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint256 public count;
    // Declare an event. 'indexed' arguments make filtering more efficient.
    event CountChanged(
        address indexed changer, 
        uint256 newCount, 
        string action,
        uint256 timestamp
    );
    constructor() {
        count = 0;
    }
    function increment() public {
        count++;
        // Emit the event after the count changes
        emit CountChanged(msg.sender, count, "incremented", block.timestamp);
    }
    function decrement() public {
        require(count > 0, "Counter cannot go below zero");
        count--;
        // Emit the event after the count changes
        emit CountChanged(msg.sender, count, "decremented", block.timestamp);
    }
    function getCount() public view returns (uint256) {
        return count;
    }
}

Key Event Features

**indexed** Parameters: The address indexed changer parameter allows for efficient filtering. You can listen for events from specific addresses.

Event Data: Non-indexed parameters (newCount, action, timestamp) contain the actual data you want to track.

Redeploying Your Contract

Before proceeding with the Python code, you need to redeploy this updated contract to Ganache via Remix. Follow the same steps from Part 2:

Update and compile the contract in Remix (ensure EVM version 'Paris')
Deploy to "DEV --- GANACHE PROVIDER"
Copy the new CONTRACT_ADDRESS and updated CONTRACT_ABI
Update your .env file if using a new address

⚠️ Important: The event definition will be included in the new ABI, so you must update it in your code.

Building an Event Listener

Let's create a dedicated event listener script that continuously monitors for CountChanged events:

# event_listener.py - Real-time event monitoring

import os
import json
import time
from datetime import datetime
from web3 import Web3, HTTPProvider
from web3.middleware import ExtraDataToPOAMiddleware
from dotenv import load_dotenv
# Load environment variables
load_dotenv()
# Configuration
RPC_URL = os.getenv("RPC_URL")
# Validation
if not RPC_URL:
    raise ValueError("RPC_URL not found in .env file.")
class EventListener:
    def __init__(self, rpc_url, contract_address, contract_abi):
        """Initialize the event listener with web3 connection and contract."""
        self.w3 = Web3(HTTPProvider(rpc_url))

        # Add PoA middleware for Ganache compatibility
        self.w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)

        # Verify connection
        if not self.w3.is_connected():
            raise ConnectionError(f"Failed to connect to Ethereum node at {rpc_url}")

        print(f"✅ Successfully connected to Ethereum node at {rpc_url}")

        # Create contract instance
        self.contract = self.w3.eth.contract(
            address=contract_address, 
            abi=contract_abi
        )

        # Create event filter
        self.event_filter = self.contract.events.CountChanged.create_filter(
            from_block='latest'
        )

        print(f"✅ Listening for 'CountChanged' events on contract: {contract_address}")
        print("🚀 Now, run your 'app.py' script in a SEPARATE terminal to trigger transactions.")
        print("Press Ctrl+C to stop listening.\n")

    def handle_event(self, event):
        """Process a single event, extracting and displaying its details."""
        print("--- 🔔 NEW EVENT DETECTED! ---")
        print(f"  Block Number: {event['blockNumber']}")
        print(f"  Transaction Hash: {event['transactionHash'].hex()}")
        print(f"  Gas Used: {event['gasUsed'] if 'gasUsed' in event else 'N/A'}")

        # Event arguments are accessible via event.args
        print(f"  Changer: {event.args.changer}")
        print(f"  New Count: {event.args.newCount}")
        print(f"  Action: {event.args.action}")

        # Convert timestamp to readable format
        timestamp = datetime.fromtimestamp(event.args.timestamp)
        print(f"  Timestamp: {timestamp.strftime('%Y-%m-%d %H:%M:%S')}")

        print("----------------------------\n")

    def start_listening(self, poll_interval=2):
        """Start the event listening loop."""
        try:
            while True:
                # Get new events since last check
                new_events = self.event_filter.get_new_entries()

                for event in new_events:
                    self.handle_event(event)

                # Wait before next poll
                time.sleep(poll_interval)

        except KeyboardInterrupt:
            print("\n🛑 Stopped listening for events.")
        except Exception as e:
            print(f"\n❌ Error occurred: {e}")
            print("Please ensure your CONTRACT_ADDRESS and CONTRACT_ABI are correct.")
# Main execution
if __name__ == "__main__":
    # IMPORTANT: Replace with your newly deployed contract details
    CONTRACT_ADDRESS = "0xYourNEWLYDeployedCounterWithEventContractAddressHere"

    CONTRACT_ABI = json.loads('''[
        {
            "inputs": [],
            "name": "count",
            "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
            "stateMutability": "view",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "getCount",
            "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
            "stateMutability": "view",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "increment",
            "outputs": [],
            "stateMutability": "nonpayable",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "decrement",
            "outputs": [],
            "stateMutability": "nonpayable",
            "type": "function"
        },
        {
            "anonymous": false,
            "inputs": [
                {
                    "indexed": true,
                    "internalType": "address",
                    "name": "changer",
                    "type": "address"
                },
                {
                    "indexed": false,
                    "internalType": "uint256",
                    "name": "newCount",
                    "type": "uint256"
                },
                {
                    "indexed": false,
                    "internalType": "string",
                    "name": "action",
                    "type": "string"
                },
                {
                    "indexed": false,
                    "internalType": "uint256",
                    "name": "timestamp",
                    "type": "uint256"
                }
            ],
            "name": "CountChanged",
            "type": "event"
        }
    ]''')

    try:
        # Create and start the event listener
        listener = EventListener(RPC_URL, CONTRACT_ADDRESS, CONTRACT_ABI)
        listener.start_listening()

    except Exception as e:
        print(f"❌ Failed to start event listener: {e}")
        print("\nTroubleshooting checklist:")
        print("• Ensure Ganache is running on the correct port")
        print("• Verify contract address and ABI are correct and up-to-date")
        print("• Check that the contract has been redeployed with events")

Here's how to test your event listener in action:

Step 1: Start the Event Listener

Open your first terminal and run:

python event_listener.py

You should see:

Step 2: Trigger Transactions

In a second terminal, run your transaction script from Part 3:

python app.py

Note: Remember to update your Part 3*app.py* with the new contract address and ABI!

Step 3: Watch the Magic Happen

As soon as your increment() transaction is mined on Ganache, the event listener should detect the CountChanged event and display:

Try running app.py multiple times, and you'll see new events appear in real-time for each transaction!

Advanced Event Filtering

You can create more sophisticated event filters:

# Filter events from a specific address
specific_filter = contract.events.CountChanged.create_filter(
    fromBlock='latest',
    argument_filters={'changer': '0x742d35Cc6634C0532925a3b8D4017b22448F6cB2'}
)

# Filter events from the last 100 blocks
historical_filter = contract.events.CountChanged.create_filter(
    fromBlock=w3.eth.block_number - 100,
    toBlock='latest'
)
# Get all historical events
all_events = contract.events.CountChanged.get_all_entries()

While polling (using get_new_entries() with time.sleep()) is simple to understand and implement, it's not the most efficient for highly real-time applications due to the polling interval delay.

For truly instant, real-time event streams, web3.py supports WebSockets.

With WebSockets, the node "pushes" events to your application as soon as they occur, eliminating the need for constant polling.

Here's a basic WebSocket example:

# websocket_listener.py - Real-time WebSocket event streaming

import asyncio
import json
from web3 import AsyncWeb3
from web3.providers.websocket import WebSocketProvider
async def websocket_event_listener():
    """Async event listener using WebSockets for real-time updates."""

    # Note: Ganache doesn't support WebSockets by default
    # You'll need to use a provider like Infura or Alchemy for this
    WS_URL = "wss://mainnet.infura.io/ws/v3/YOUR_PROJECT_ID"

    async with AsyncWeb3.persistent_websocket(
        WebSocketProvider(WS_URL)
    ) as w3:

        # Create contract instance
        contract = w3.eth.contract(
            address=CONTRACT_ADDRESS,
            abi=CONTRACT_ABI
        )

        # Create event filter
        event_filter = await contract.events.CountChanged.create_filter(
            fromBlock='latest'
        )

        # Listen for events
        async for event in event_filter.watch(poll_interval=0.1):
            print(f"Real-time event: {event}")
# Run the async listener
# asyncio.run(websocket_event_listener())

Note: This is more advanced and typically involves *asyncio* for asynchronous programming, but it's the gold standard for production-grade real-time dApps.

Common Event Patterns in DeFi

Understanding events is crucial for building sophisticated DeFi applications. Here are some common patterns:

Token Transfer Events

event Transfer(address indexed from, address indexed to, uint256 value);

DEX Swap Events

event Swap(\
    address indexed sender,\
    uint256 amount0In,\
    uint256 amount1In,\
    uint256 amount0Out,\
    uint256 amount1Out,\
    address indexed to\
);

NFT Transfer Events

event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);

Production Considerations

When building production applications:

🔐 Error Handling: Implement robust error handling for network failures and reconnection logic.

📊 Rate Limiting: Be mindful of RPC provider rate limits, especially with frequent polling.

💾 Event Storage: Consider storing important events in a database for historical analysis.

⚡ Performance: Use indexed parameters for efficient filtering on large datasets.

🔄 Reconnection Logic: Implement automatic reconnection for WebSocket connections.

Troubleshooting Common Issues

Events Not Appearing

Verify the contract has been redeployed with the updated ABI
Check that transactions are actually being mined (not just sent)
Ensure your event filter is using the correct contract address

Connection Issues

Confirm Ganache is running on the expected port
Check that your RPC URL is correct in the .env file
Verify the middleware is properly injected

Performance Problems

Reduce polling interval if missing events
Consider using WebSockets for high-frequency applications
Implement proper error handling and retry logic

What You've Accomplished

You've just unlocked a powerful capability for building dynamic and responsive dApps! You now know how to:

✅ Design event-driven smart contracts with efficient event emission

✅ Create event listeners that monitor blockchain activity in real-time

✅ Implement both polling and WebSocket approaches for different use cases

This ability to react to on-chain activity is fundamental for:

User interfaces that update in real-time
Analytics dashboards tracking DeFi activity
Automated trading bots and arbitrage systems
Notification systems for important blockchain events

Resources for Further Learning:

Ethereum Event Logs: Understanding event mechanics
Solidity Events Best Practices: Efficient event design

Questions about events or need help with your implementation? Drop a comment below and I'll help you troubleshoot.

Part 3: Sending Your First Blockchain Transaction with web3.py --- From Reading to Writing

Divine Igbinoba — Sun, 06 Jul 2025 20:41:54 +0000

Welcome back, blockchain explorers! In Part 1, we connected to our local Ganache blockchain and learned to read fundamental data like block numbers and balances. In Part 2, you deployed your Counter smart contract and read its initial state using web3.py.

Now comes the exciting part: changing the state of our smart contract. We'll make our Counter actually increment its value on the blockchain. This is where your code interacts directly with the decentralized ledger by sending your first transaction!

Understanding Blockchain Transactions

Unlike "read" operations (like w3.eth.block_number or contract.functions.getCount().call()), which are free and don't alter the blockchain, "write" operations require a transaction.

Think of it like this:

Reading (View Function): Asking "What's my bank balance?"; a free inquiry
Writing (Transaction): Transferring money or making a payment; this changes your balance and requires verification

Key Transaction Characteristics

Every blockchain transaction has three essential components:

1. Gas Costs Every transaction on Ethereum requires a fee known as gas, paid in the native currency (ETH for Ethereum, MATIC for Polygon, etc.). Gas ensures:

Network validators are compensated for computational resources
Transaction processing and block inclusion costs are covered
The network remains secure and spam-resistant

2. Cryptographic Signatures To prove you authorize the transaction, it must be cryptographically signed with your account's private key. This signature ensures authenticity and integrity.

🔒 Security Note: Your private key never leaves your machine during this process; only the signature is sent to the node.

3. Nonce Management Each transaction from a specific account must include a unique, incrementing number called a nonce (short for "number used once"). This mechanism:

Ensures transactions are executed in order
Prevents duplicate or replayed transactions
Must be unique for each transaction from the same address

Updating Our Counter Contract

Let's enhance our Counter.sol contract to include functions that can actually change its state: increment() and decrement().

// Counter.sol (updated with increment/decrement functions)
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint256 public count;
    constructor() {
        count = 0;
    }
    // Function to increment the counter
    function increment() public {
        count++;
    }
    // Function to decrement the counter
    function decrement() public {
        count--;
    }
    // View function to get current count
    function getCount() public view returns (uint256) {
        return count;
    }
}

Redeploying Your Contract

Before proceeding, you need to redeploy this updated contract to Ganache via Remix: Follow the same steps from Part 2:

Update the code: Paste the new code into Counter.sol in Remix
Compile: Ensure EVM version 'Paris' is selected
Deploy: Go to "Deploy & Run Transactions" tab
Connect: Ensure "DEV-GANACHE PROVIDER" is selected and connected
Deploy: Click the "Deploy" button
Save details: Copy the new CONTRACT_ADDRESS and updated CONTRACT_ABI

⚠️ Important: The ABI now includes *increment* and *decrement* functions, so you must update it in your code.

Setting Up Your Sender Account (Securely!)

To send a transaction, you need an account with some Ether (or Ganache ETH) and its private key.

Getting a Private Key from Ganache

Open your Ganache Desktop application.
Navigate to the "ACCOUNTS" tab, you'll see a list of pre-funded accounts.
Click the "key" icon next to the first account (the one with the most ETH).

Image: Screenshot of Ganache Desktop, highlighting the key icon next to an account.

4. Copy the private key from the dialogue that appears.

Image: Screenshot of Ganache Desktop showing the private key dialog.

Secure Storage with Environment Variables

Never hardcode private keys directly in your script! Update your .env file:

# .env
RPC_URL="http://127.0.0.1:7545"

# Private key for your Ganache account
GANACHE_PRIVATE_KEY="0xYOUR_GANACHE_PRIVATE_KEY_HERE"

🚨 Production Warning: For real-world applications on public networks, never use private keys directly like this. Instead, use secure key management solutions (hardware wallets, KMS, etc.). For local development with Ganache, this approach is acceptable.

The Transaction Workflow: Build, Sign, Send, Wait

Sending a transaction with web3.py involves four critical steps:

Build: Create the raw transaction dictionary, specifying who it's from, who it's to (the contract address), what function to call, its arguments, and gas parameters.

 increment_txn = contract.functions.increment().build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 2000000,
        'gasPrice': w3.eth.gas_price
    })

2. Sign: Cryptographically sign the transaction with your private key (locally)

signed_txn = w3.eth.account.sign_transaction(increment_txn, private_key=PRIVATE_KEY)

3. Send: Send the signed transaction data to the Ethereum node

tx_hash = w3.eth.send_raw_transaction(signed_txn.raw_transaction)

4. Wait: Wait for the transaction to be included in a block and get the receipt

tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

Now let's implement this to increment our Counter!

Complete Implementation

Here's the complete updated app.py script:

# app.py - Complete transaction implementation

import os
import json
from web3 import Web3, HTTPProvider
from web3.middleware import ExtraDataToPOAMiddleware
from eth_account import Account
from dotenv import load_dotenv
# Load environment variables
load_dotenv()
# Configuration
RPC_URL = os.getenv("RPC_URL")
PRIVATE_KEY = os.getenv("GANACHE_PRIVATE_KEY")
# Validation
if not RPC_URL or not PRIVATE_KEY:
    raise ValueError("RPC_URL or GANACHE_PRIVATE_KEY not found in .env file.")
try:
    # Initialize Web3 connection
    w3 = Web3(HTTPProvider(RPC_URL))

    # Add PoA middleware for Ganache compatibility
    w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)

    # Verify connection
    if not w3.is_connected():
        print(f"❌ Failed to connect to Ethereum node at {RPC_URL}")
        exit()

    print(f"✅ Successfully connected to Ethereum node at {RPC_URL}")

    # Set up sender account
    sender_account = Account.from_key(PRIVATE_KEY)
    sender_balance = w3.from_wei(w3.eth.get_balance(sender_account.address), 'ether')

    print(f"\n🔑 Sender Account Address: {sender_account.address}")
    print(f"💰 Sender Account Balance: {sender_balance} ETH")

    # Smart Contract Setup
    print("\n--- Smart Contract Transaction ---")

    # IMPORTANT: Replace with your newly deployed contract details
    CONTRACT_ADDRESS = "0xYourNEWLYDeployedCounterContractAddressHere"
    CONTRACT_ABI = json.loads('''[
        {
            "inputs": [],
            "name": "count",
            "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
            "stateMutability": "view",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "getCount",
            "outputs": [{"internalType": "uint256", "name": "", "type": "uint256"}],
            "stateMutability": "view",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "increment",
            "outputs": [],
            "stateMutability": "nonpayable",
            "type": "function"
        },
        {
            "inputs": [],
            "name": "decrement",
            "outputs": [],
            "stateMutability": "nonpayable",
            "type": "function"
        }
    ]''')

    # Create contract instance
    contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=CONTRACT_ABI)

    # Get current counter value
    current_count = contract.functions.getCount().call()
    print(f"🔢 Current Counter Value: {current_count}")

    # Transaction Process
    print("\n--- Transaction Process ---")

    # Step 1: Get current nonce
    nonce = w3.eth.get_transaction_count(sender_account.address)
    print(f"📊 Current Nonce: {nonce}")

    # Step 2: Build transaction
    increment_txn = contract.functions.increment().build_transaction({
        'from': sender_account.address,
        'nonce': nonce,
        'gas': 100000,  # Reasonable gas limit for simple operations
        'gasPrice': w3.eth.gas_price
    })

    print(f"📄 Transaction built successfully")
    print(f"   Gas Limit: {increment_txn['gas']}")
    print(f"   Gas Price: {increment_txn['gasPrice']} wei")

    # Step 3: Sign transaction
    signed_txn = w3.eth.account.sign_transaction(increment_txn, private_key=PRIVATE_KEY)
    print(f"✍️ Transaction signed")

    # Step 4: Send transaction
    tx_hash = w3.eth.send_raw_transaction(signed_txn.raw_transaction)
    print(f"🚀 Transaction sent! Hash: {tx_hash.hex()}")

    # Step 5: Wait for confirmation
    print("⏳ Waiting for transaction to be mined...")
    tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

    # Check transaction status
    if tx_receipt['status'] == 1:
        print("\n🎉 Transaction successful!")
        print(f"   Block Number: {tx_receipt['blockNumber']}")
        print(f"   Gas Used: {tx_receipt['gasUsed']}")

        # Verify the state change
        new_count = contract.functions.getCount().call()
        print(f"🔢 New Counter Value: {new_count}")
        print(f"   Increment: {current_count} → {new_count}")
    else:
        print("\n❌ Transaction failed!")
        print("Check your contract address, ABI, and account balance.")
except Exception as e:
    print(f"\n❌ Error occurred: {e}")
    print("\nTroubleshooting checklist:")
    print("• Ensure Ganache is running on the correct port")
    print("• Verify contract address and ABI are correct")
    print("• Check that sender account has sufficient ETH")
    print("• Confirm private key is valid")
print("\n--- End of Transaction Process ---")

Why ExtraDataToPOAMiddleware Matters

I'll be honest with you; I didn't include this middleware in my first attempts, and it cost me hours of debugging frustration. When I tried connecting to a Polygon testnet to expand my testing, I kept hitting this cryptic error:

web3.exceptions.ExtraDataLengthError: The field extraData is 97 bytes, but should be 32

I was pulling my hair out! The same code worked perfectly on Ganache but failed miserably on other networks. After struggling with ChatGPT and digging through Stack Overflow threads, I finally discovered the culprit.

Here's what's happening: The Ethereum Yellow Paper limits extraData to 32 bytes, but Proof-of-Authority (PoA) chains like Polygon, Goerli, Rinkeby, Sepolia, and BSC stuff additional validator metadata into this field - sometimes up to 97 bytes or more!

That innocent-looking line in our code:

w3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)

This middleware patches the extraData field on the fly, allowing web3.py to parse blocks from PoA chains that would otherwise crash your application.

💡 Learn from my mistakes: Even when working with standard Ethereum, always include this middleware. It's a small addition that saves you from potential headaches when you eventually deploy to testnets or other networks.

Running Your Transaction

Execute your script:

python app.py

You should see output similar to:

Image: Script output.

Run it again, and the count becomes 2, then 3, and so on. You're now successfully writing data to the blockchain!

What You've Accomplished

This is a significant milestone! You've successfully:

✅ Understood transaction concepts: Understanding gas, nonces, and cryptographic signing

✅ Implemented the complete transaction workflow: Building, signing, sending, and confirming

✅ Changed blockchain state: Successfully modifying your smart contract's data

✅ Handled network compatibility: Using middleware for different blockchain networks

This capability unlocks vast possibilities, from sending tokens to interacting with complex DeFi protocols.

Common Troubleshooting

If you encounter issues:

Connection Problems

Ensure Ganache is running on the correct port (usually 7545)
Check that your RPC_URL matches Ganache's settings

Transaction Failures

Verify your contract address and ABI are correct and up-to-date
Ensure your sender account has sufficient ETH for gas fees
Check that your private key is valid and corresponds to a funded account

Gas Estimation Issues

Try increasing the gas limit if transactions fail
On testnets, gas prices can be volatile, consider using w3.eth.gas_price for current rates

What's Next?

In Part 4, we'll explore another critical aspect of dApp development: listening for smart contract events to get real-time updates from the blockchain. You'll learn how to:

Set up event listeners for your contracts
Filter and process blockchain events
Build responsive applications that react to on-chain changes

Resources for Further Learning:

web3.py Documentation --- Comprehensive API reference
Ethereum Gas Explained --- Deep dive into gas mechanics
Smart Contract Security --- Security best practices

Found this tutorial helpful? Follow me for more blockchain development content and don't forget to clap if this helped you send your first transaction! 👏

Have questions or run into issues? Drop a comment below and I'll help you troubleshoot.

Part 2: Reading Smart Contract Data with web3.py - Your First Contract Interaction (No Faucets Needed!)

Divine Igbinoba — Mon, 30 Jun 2025 21:12:05 +0000

Welcome back to our web3.py series! In Part 1, we got our development environment set up and learned how to connect to an Ethereum node to read basic blockchain data like block numbers and gas prices.

Now, it's time to interact with smart contracts. These are the self-executing programs stored on the blockchain that power decentralised applications (dApps). Just like you interact with a web API to get data from a traditional server, you'll use web3.py to "talk" to smart contracts on the blockchain.

Smart Contracts: The Programmable Building Blocks of Web3

A smart contract is essentially a piece of code that lives on the blockchain. Once deployed, it runs exactly as programmed, without any possibility of censorship, downtime, or third-party interference.

To interact with a smart contract from web3.py, you primarily need two pieces of information:

The Contract's Address: This is its unique location on the blockchain (e.g., 0xDE893...).
The Contract's ABI (Application Binary Interface): This is a JSON description of the contract's public functions and events. Think of the ABI as the "instruction manual" for your web3.py client.
It tells web3.py what functions the contract has, what arguments they take, and what values they return. Without the ABI, web3.py wouldn't know how to correctly encode your function calls or decode the contract's responses.

Your First Smart Contract: The Simple Counter

To make this hands-on, we're going to use a super simple Counter smart contract. This contract will store a single number (count) and allow us to read its current value.

Here's the Solidity code for our Counter contract:

// Counter.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Counter {
    uint public count; // A public state variable, automatically creates a getter function
    constructor() {
        count = 0; // Initialize count to 0 when the contract is deployed
    }
    // A 'view' function to explicitly get the count
    // 'view' means it only reads state and doesn't modify it (no gas cost for calling)
    function getCount() public view returns (uint) {
        return count;
    }
}

This contract has:

A count variable, initialised to 0. The public keyword automatically creates a count() getter function for us.
A getCount() function, which is explicitly declared as public view. Both count() and getCount() are view functions, meaning they only read the contract's state and do not modify it.

Hands-On: Deploying Your Contract to Ganache (Skip the Faucet Frustration!)

When I first started learning blockchain development, I spent countless hours hunting for free testnet tokens from faucets. Every time I ran out, it was another delay, another break in my learning flow. It consumed so much of my valuable learning time.

This is exactly why local development with Ganache is crucial. You get instant transactions, unlimited "test Ether," and complete control over your environment. No more waiting for faucets, no more empty wallets interrupting your flow, just pure, uninterrupted learning.

In Part 1, we learned about connecting web3.py to your local Ganache blockchain. Now, we'll deploy our Counter.sol contract directly to that Ganache blockchain using Remix IDE. This ensures your Python script can interact with the contract you've deployed!

For this project, we will be using Remix IDE for easy development and deployment. While we'll start with Remix's built-in deployment features, we may explore deploying through code later.

Step-by-step guide to deploy your Counter contract to Ganache with Remix:

1. Open Ganache Desktop: First, ensure your Ganache Desktop application is open and running. You should see its "Quickstart" workspace active, showing accounts and current blocks.

2. Open Remix IDE: Open your web browser and navigate to https://remix.ethereum.org/.

3. Create a New File:

On the left sidebar, click on the "File Explorer" icon (looks like a folder).
Under "contracts", click the "Create new file" icon (a blank paper with a plus sign).
Name the file Counter.sol and press Enter.

4. Paste the Contract Code: Copy the Counter.sol code from above and paste it into the Counter.sol file in Remix.

5. Compile the Contract and Get the ABI:

Click on the "Solidity Compiler" icon on the left sidebar (looks like a Solidity logo).
Ensure the "Compiler" version matches our pragma solidity ^0.8.0; (e.g., 0.8.20).
Click on "Advanced configurations" (it might be a dropdown or expandable section)
From the "EVM version" dropdown, select "Paris".

Click on the light blue "Compile Counter.sol" button.

You should see a green checkmark on the compiler icon if compilation is successful (as in the image above).
Now, scroll down within the Solidity Compiler tab until you see the "ABI" section (it might be a button or a copy icon next to the ABI output). Click the copy ABI button.

6. Connect Remix to Ganache (Environment Setup):

Click on the "Deploy & Run Transactions" icon on the left sidebar (just below that "Solidity Compiler" icon).
In the "Environment" dropdown, select "Customize this list..."

Scroll down in the "Environment Customization" list until you see "DEV --- GANACHE PROVIDER". Check its checkbox.

Click the "Environment" dropdown again. Now you'll see "DEV --- GANACHE PROVIDER" on the list --- click it.

Remix will likely pop up a small window asking for the Ganache RPC endpoint. Copy your Ganache RPC URL from your Ganache application's "Accounts" section (it's typically http://127.0.0.1:7545 by default) and paste it into the Remix prompt. Then click "OK".

7. Deploy the Contract to Ganache:

In Remix, ensure "Counter" is selected in the "Contract" dropdown.
Click the orange "Deploy" button.

You should see a new transaction appear in your Ganache Desktop application under the "Transactions" tab, confirming the deployment.

8. Get Contract Address:

After successful deployment, expand the "Deployed Contracts" section below the Deploy button in Remix. You'll see your Counter contract listed with its address (e.g., COUNTER AT 0x...).
Click the copy icon next to the address to save it. This is your CONTRACT_ADDRESS.

In case you're wondering why we changed the Remix EVM to 'Paris' for Ganache...

The 'EVM version' in Remix and the 'Hardfork' setting in Ganache both refer to specific versions of the Ethereum protocol. These different versions incorporate various updates, bug fixes, and new features.

For successful interaction and deployment, it's crucial that your chosen EVM version in Remix (which determines how your contract's bytecode is compiled) is compatible with the hardfork setting of your local Ganache blockchain. This ensures that the environment where your contract is compiled and the environment where it's deployed understand and execute the same set of rules. Setting Remix to 'Paris' generally provides good compatibility with recent Ganache versions.

Reading Your Contract's Data with web3.py

Now that you have your CONTRACT_ADDRESS and CONTRACT_ABI from your Ganache deployment, let's update our app.py script to interact with it.

Open your app.py from Part 1. We'll add a new section.

import json  # Import json for parsing the ABI string

# --- Smart Contract Interaction ---

print("\n--- Smart Contract Interaction ---")


# IMPORTANT: Replace with the actual address you copied from Remix (deployed to Ganache)
CONTRACT_ADDRESS = "0xD369F9Eefd646054F3E46D97D45e2E88030F9A80"  # e.g., "0x5FbDB2315678afecb367f032d93F642f64180aa3"


# IMPORTANT: Paste your ENTIRE ABI here. It's a long JSON string.
# The ABI below is what you should get from our simple Counter contract.
# Make sure to replace this with the exact ABI you copied from Remix!
CONTRACT_ABI = json.loads('''
[
    {
        "inputs": [],
        "stateMutability": "nonpayable",
        "type": "constructor"
    },
    {
        "inputs": [],
        "name": "count",
        "outputs": [
            {
                "internalType": "uint256",
                "name": "",
                "type": "uint256"
            }
        ],
        "stateMutability": "view",
        "type": "function"
    },
    {
        "inputs": [],
        "name": "getCount",
        "outputs": [
            {
                "internalType": "uint256",
                "name": "",
                "type": "uint256"
            }
        ],
        "stateMutability": "view",
        "type": "function"
    }
]
''')

try:
    # Create a contract object: This tells web3.py how to interact with your deployed contract
    contract = w3.eth.contract(address=CONTRACT_ADDRESS, abi=CONTRACT_ABI)

    print(f"✅ Contract loaded successfully at address: {CONTRACT_ADDRESS}")


    # Call the 'getCount()' view function
    # View functions don't change state, so they are free and instant.
    # We use .call() to execute them.
    current_count_from_get_function = contract.functions.getCount().call()
    print(f"\n🔢 Current Counter Value (via getCount() function): {current_count_from_get_function}")


    # Access the 'count' public state variable directly
    # Public state variables automatically get a getter function generated by Solidity.
    # This also uses .call() and is free.
    current_count_from_public_var = contract.functions.count().call()
    print(f"🔢 Current Counter Value (via 'count' public variable): {current_count_from_public_var}")

    # Note: Both methods above do the same thing - they read the current value
    # without modifying the blockchain state, which is why they're free to call


except Exception as e:
    print(f"❌ Error interacting with contract: {e}")
    print("Please ensure your CONTRACT_ADDRESS and CONTRACT_ABI are correct and match your deployed contract.")
    print("Also, ensure your Ganache is running and Remix was successfully connected to 'DEV - GANACHE PROVIDER' and deployed to Ganache.")

print("\n--- End of Smart Contract Interaction ---")

Important: Make sure you replace CONTRACT_ADDRESS and the content of CONTRACT_ABI with the exact values you copied from Remix after deploying to Ganache!

Now, run your app.py script again:

python app.py

You should see output similar to this, showing the initial count of 0:

Troubleshooting Common Issues

If you encounter errors, here are the most common causes and solutions:

"Error interacting with contract":

Double-check that your CONTRACT_ADDRESS is correct and matches what you copied from Remix
Ensure your CONTRACT_ABI is valid JSON (no trailing commas, proper quotes)
Verify that Ganache is still running on the same port

"Connection refused":

Make sure Ganache Desktop is running
Check that the RPC URL in your app.py matches Ganache's RPC server URL
Go back to Part 1 to double-check your RPC setup if you're still having connection issues

"Invalid address":

Contract addresses should start with 0x and be 42 characters total
Make sure you copied the entire address from Remix

What You've Achieved

Congratulations! You've successfully:

Deployed your very own smart contract to your local Ganache blockchain
Used web3.py to read data directly from a smart contract
Set up a complete local development environment for blockchain applications

This is a fundamental step in building any dApp that needs to display information from the blockchain. You now understand how to bridge the gap between your Python application and smart contracts running on Ethereum.

Coming Up in Part 3

In the next post, things get even more exciting! We'll learn how to:

Change the state of our smart contract (increment that counter!)
Send transactions that modify blockchain data

Get ready to truly interact with the blockchain by writing data, not just reading it!

Part 1: Your Python Gateway to Blockchain – Getting Started with `web3.py`

Divine Igbinoba — Fri, 20 Jun 2025 08:48:46 +0000

Everyone talks about JavaScript for web3 development, but here's the thing - Python works just fine. Actually, it works really well, especially when you've got libraries like web3.py doing the heavy lifting.

I spent way too much time at the beginning trying to figure out how to connect my Python backend to blockchain networks. Turns out, once you get past the initial setup hurdles, it's surprisingly straightforward.

If you’re a Python dev curious about crypto, or working on a backend that needs to talk to a blockchain, this guide is for you.

Web3.py

Imagine your blockchain network as a complex smart home, filled with devices like smart lights, thermostats, and security cameras. Each device understands a unique, complicated set of signals. Controlling them manually would be chaos.

Now imagine having one remote that works with everything. You press "lights on" and it figures out the exact signals to send. That's basically what web3.py does for blockchain interaction.

Without it, you'd be manually crafting JSON-RPC requests (which I definitely tried at first - not fun). With it, you write normal Python code and let the library handle all that network protocol stuff behind the scenes.

What Actually Is web3.py?

It's a Python library that translates your regular Python commands into the JSON-RPC calls that Ethereum nodes understand. Remember those RPC requests we talked about before? This library handles all of that for you.

So instead of manually constructing this:

{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}

You just write:

w3.eth.block_number

Much better, right?

With web3.py you can query data, send transactions, and interact with smart contracts, all with clean Python code.

Getting Started: Installation and Setup

Let's get this thing working. First, the usual Python project setup:

mkdir my-web3-app
cd my-web3-app
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install web3 python-dotenv

Connecting to an Ethereum Node (Your RPC Provider)

Here's where I got stuck initially. To talk to any blockchain, you need to connect to a node. These are computers running blockchain software that maintain copies of the ledger.

You've got two main options:

*1: Use a service like Infura or Alchemy *

These companies run blockchain nodes for you. Sign up, get an API key, and you're connected to the real Ethereum network. Great for production

How to get one: Sign up for a free account at Infura.io](https://www.infura.io/) or Alchemy.com. Create a new project for the Ethereum Mainnet or a testnet (e.g., Sepolia) and copy your HTTP endpoint URL.

*2: Run your own local blockchain *

When I first started, I didn’t know this was a thing. I was constantly hunting for testnet faucets and hitting request limits. Then I discovered Ganache.

It spins up a personal Ethereum blockchain on your machine. Perfect for local testing, and it gives you free ETH (fake, of course).

For this tutorial, we're going with Option 2 using Ganache. Trust me on this one - it'll save you so much hassle while learning.

Setting Up Ganache
* Download Ganache Desktop (easiest for beginners).
* Install it and launch. It will automatically start a local blockchain with pre-funded accounts and display its RPC server address (usually http://127.0.0.1:7545).

If you're having trouble setting it up, check this put

If you use local you can get your url here in Gananche once you've installed it.

Keeping Your Secrets Safe

Before we write any code, let's set up environment variables. Create a .env file in your project folder:

# .env
RPC_URL="http://127.0.0.1:7545"

# Later, when you want to use Infura:
# RPC_URL="https://mainnet.infura.io/v3/YOUR_PROJECT_ID"

And add this to a .gitignore file so you don't accidentally commit your API keys:

.env
venv/

Your First Connection

Now for the actual Python code. Create app.py:

# app.py
import os
from web3 import Web3, HTTPProvider
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get the RPC URL from environment variables
RPC_URL = os.getenv("RPC_URL")

# Ensure the RPC_URL is set
if not RPC_URL:
    raise ValueError("RPC_URL not found in .env file. Please set it (e.g., GANACHE_URL or INFURA_URL).")

try:
    # Initialize Web3.py with an HTTP provider
    w3 = Web3(HTTPProvider(RPC_URL))

    # Test the connection to the Ethereum node
    if w3.is_connected():
        print(f"✅ Successfully connected to Ethereum node at {RPC_URL}")
    else:
        print(f"❌ Failed to connect to Ethereum node at {RPC_URL}")
        # Exit if connection fails, as subsequent operations will also fail
        exit()

except Exception as e:
    print(f"An error occurred during connection: {e}")
    exit()

Run it with python app.py. If Ganache is running, you should see the success message.

If you've set up Ganache and it's running, you should see ✅ Successfully connected.... If you use Infura, you'll see a similar message.

Actually Reading From the Blockchain

Now comes the fun part. Let's ask the blockchain some questions:

# app.py (continued from above)

# --- Your First Blockchain Reads ---

print("\n--- Basic Blockchain Data ---")

# 1. Get the latest block number
# This is equivalent to the eth_blockNumber RPC call
latest_block_number = w3.eth.block_number
print(f"📈 Latest Block Number: {latest_block_number}")

# 2. Get the current gas price
# Gas price is returned in Wei (the smallest unit of Ether)
gas_price_wei = w3.eth.gas_price
print(f"⛽ Current Gas Price (Wei): {gas_price_wei}")

# Wei is tiny! Let's convert it to more readable units.
# 1 Ether = 10^18 Wei
# 1 Gwei = 10^9 Wei
print(f"⛽ Current Gas Price (Gwei): {w3.from_wei(gas_price_wei, 'gwei')} Gwei")
print(f"⛽ Current Gas Price (Ether): {w3.from_wei(gas_price_wei, 'ether')} ETH")


# 3. Get an account's Ether balance
# For Ganache, you can use one of the pre-funded accounts.
# If using Infura, pick any public Ethereum address.
if "ganache" in RPC_URL.lower():
    # Get the first account Ganache provides
    account_to_check = w3.eth.accounts[0]
else:
    # Example public address (Vitalik Buterin's ENS primary address on Mainnet)
    account_to_check = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

balance_wei = w3.eth.get_balance(account_to_check)
print(f"\n💰 Balance of {account_to_check} (Wei): {balance_wei}")
print(f"💰 Balance of {account_to_check} (Ether): {w3.from_wei(balance_wei, 'ether')} ETH")

# 4. Get details of a specific block (e.g., the latest block)
block_info = w3.eth.get_block(latest_block_number)
print(f"\n📄 Details for Block {latest_block_number}:")
print(f"  Hash: {block_info['hash'].hex()}") # Convert bytes to hex string for display
print(f"  Miner: {block_info['miner']}")
print(f"  Timestamp: {block_info['timestamp']} (Unix)")
print(f"  Number of Transactions: {len(block_info['transactions'])}")

print("\n--- End of Basic Reads ---")

Run python app.py again, and you'll see all this blockchain data printed to your console!

You probably noticed all those w3.from_wei() calls. Here's the deal: Ethereum uses really tiny units internally to avoid floating-point math errors.

1 ETH = 1,000,000,000,000,000,000 wei (that's 18 zeros)
1 ETH = 1,000,000,000 gwei (9 zeros)

So when the blockchain returns 20000000000, that's actually 20 gwei, not 20 ETH. The conversion functions save you from doing that math yourself.

What You Just Accomplished

Pretty cool, right? You just:

Connected Python to a blockchain network

Queried live blockchain data
Handled the weird unit conversions automatically
Did it all with clean, readable Python code

No manual JSON-RPC construction, no hex encoding/decoding headaches, no network protocol debugging. Just Python talking to blockchain.

What's Coming Next

Next time, we're going to deploy and interact with smart contracts. That's where things get really interesting - calling functions, sending transactions, handling events.

But first, play around with this code.

Quick troubleshooting: If Ganache won't start, check if port 7545 is already in use. If you're getting connection errors, make sure your .env file is in the right directory and the RPC_URL is uncommented.

A Beginner’s Guide to RPC in Web3

Divine Igbinoba — Sat, 14 Jun 2025 18:13:42 +0000

For the past few months, I’ve been working on a blockchain-based backend.

Coming from a traditional backend background, I found it a bit strange connecting Python to the blockchain. One of my earliest hurdles was understanding how to actually “talk” to the blockchain.

That’s when I discovered RPCs - Remote Procedure Calls and how they power everything behind the scenes in Web3.

Here’s what I learned.

🔍 What Is an RPC?

RPC stands for Remote Procedure Call.

It’s not just a Web3 concept; it’s been around in distributed systems for a long time.

In simple terms:
RPC lets a program execute a function in another program on a different server as if it were local.

A Simple Example
Imagine you have a function like this in your local code:

def MyPage(name: str, count: int):

When you call it:

data = MyPage("my", 1)

Your program jumps to that specific function and executes it directly.

Now imagine

def MyPage(name: str, count: int):

doesn’t exist in your codebase at all—instead, it lives on another server entirely.

RPC makes it so that calling

MyPage("my", 1)

sends the request over the network, runs the function on the remote server, and sends back the result, while hiding all the networking complexity from you.

⚙️ How It Works (Under the Hood)

When you make an RPC call:

The client calls the client's stub
The client stub marshals the parameters (converts them to a format that can be transmitted over the network, like binary)
The marshalled data is sent to the remote server.
The server unmarshals the parameters back to their original format.
The server executes the function with those parameters
The server marshals the result and sends it back.
The client stub unmarshals the result and returns it to your program.

Note: Marshalling is the process of converting data into a format suitable for transmission, while unmarshalling is the reverse process.

🔗 RPC in Blockchain Networks

In web3, RPC specifically JSON-RPC, is used to communicate with blockchain network nodes and execute commands.

JSON-RPC encodes basic RPC functionality in JSON format, making it easier to communicate across different servers and programming languages.

Every JSON-RPC request consists of four key components:

Version: "jsonrpc" - specifies the RPC version (typically "2.0")
Method: "method" - the name of the function you're calling
Parameters: "params" - the arguments for the method
Unique Identifier: "id" - tracks the request/response pair

Here are some practical examples:

Example 1: Reading Blockchain Data

To check the current block number on Ethereum:
Request:

{
  "jsonrpc": "2.0",
  "method": "eth_blockNumber",
  "params": [],  // No parameters needed for this method
  "id": 1         // A unique ID for this request
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1312d00" // Hexadecimal for 20,000,000 in decimal
}

Example 2: Sending Ether (State-Changing Transaction)

NOTE: Unlike read operations, sending a transaction that modifies the blockchain state is a two-step process:

- Client-Side (Off-chain): You construct the transaction details (from, to, value, gas, nonce, etc.), then sign this transaction using the sender's private key.

- Node-Side (On-chain): You send this signed raw transaction to the Ethereum node using eth_sendRawTransaction. The node validates the signature, includes it in a block, and broadcasts it to the network.

JSON-RPC Request (after signing off-chain):

{
  "jsonrpc": "2.0",
  "method": "eth_sendRawTransaction",
  "params": [
    "0xf86c808..."
    // This very long hex string is the RLP-encoded, signed raw transaction
  ],
  "id": 4
}

JSON-RPC Response (Success):

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": "0x53b496732f..." // The transaction hash
}

The result here is the transaction hash. You can then use another RPC method (eth_getTransactionReceipt) with this hash to check the transaction outcome.

Implementation Options
To send JSON-RPC requests to blockchain networks, you have two main approaches:

1. RPC Providers

RPC providers offer hosted blockchain nodes with exposed RPC endpoints. Popular options include:

Infura
Alchemy (which I use)
QuickNode
Etherscan API
Polygon, Arbitrum, and other network-specific providers

Pros: Convenient, scalable, maintained infrastructure, high uptime
Cons: Requires subscription, rate limits, ongoing costs, less control

2. Self-Hosted Nodes

You can run your blockchain node (like Hyperledger Besu for Ethereum) and connect directly to its RPC endpoint.

Pros: Full control, no rate limits, no ongoing subscription costs
Cons: Requires maintenance, storage, bandwidth, and technical expertise.

🤯 My Early Struggles

Initially, I was doing it all manually:

Constructing JSON-RPC payloads by hand
Sending them using requests in Python
Decoding hexadecimal responses
Handling edge cases and errors myself

essentially performing all the stub activities by hand.

Here's what that looked like:


import requests
import json

# Manual RPC call - the hard way
def get_block_number_manual():
    payload = {
        "jsonrpc": "2.0",
        "method": "eth_blockNumber",
        "params": [],
        "id": 1
    }

    response = requests.post(
        "https://polygon-amoy.g.alchemy.com/v2/API_KEY",
        data=json.dumps(payload),
        headers={'content-type': 'application/json'}
    )

    result = response.json()
    # Convert hex to decimal manually
    block_number = int(result['result'], 16)
    return block_number

This approach was error-prone and tedious. Then I discovered the web3.py client library, which transformed my development experience:

from web3 import Web3

# Using web3.py - the easy way
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR_API_KEY'))
block_number = w3.eth.block_number  # That's it!

The web3.py library acts as the client stub, handling all the complexity: error handling, encoding/decoding, connection management, and more.

Key Takeaways

Understanding RPC in blockchain development opened up a whole new world for me. The key insights:
RPC makes remote function calls feel local.
JSON-RPC is the standard for blockchain communication
Use established libraries like web3.py instead of manual implementation.
RPC providers for convenience, self-hosted nodes for control

The transition from traditional backend development to blockchain becomes much smoother once you grasp these RPC fundamentals.

For a deeper dive into RPC in distributed systems, check out Understanding RPC in Distributed Systems by Christopher R. Wirz.

Forem: Divine Igbinoba

Atlas Payroll: Streaming Payroll with Operational Capital Yield on Solana

Introduction

System Overview

Operational Flow

Architecture

Technical Stack

Contract Data Structures

General Notes on Types

1. The Operator Account (ProtocolVault)

update_liability (Update Liability)

update_protocol (Safety Vault Requirement Check)

calculate_k_pool (Kamino Pool Valuation)

calculate_total_assets (Net Available Capital)

ktoken_to_burn (Redemption Calculation)

2. The Employee Account (StaffAccount)

claimable_salary

3. Kamino's Reserve Account (Reserve)

Helpers

Instruction Discriminator

Key Constants

Instructions

1. Operator Initialisation (OperatorInit)

2. Operator Deposit (Deposit)

3. Operator Withdrawal (CFOWithdraw)

4. Rebalance (Rebalance)

5. Staff Initialisation (StaffInit)

6. Staff Claim (StaffClaim)

7. Staff Offboarding (‎StaffOffboard)

8. Collect Staff (CollectStaff‎)

Testing Strategy

Testnet Setup with Surfpool

Test Cases

Running the Contract

Build

Start the local test validator (Surfpool)

Run Tests

Deploy

Run Tests

Part 7: Interacting with ERC-721 NFTs using `web3.py`

What is an ERC-721 NFT?

Key ERC-721 Functions We'll Use:

Read Functions (View):

Write Functions (State-Changing):

Hands-On: Deploying and Minting Your Own ERC-721

Interacting with Your NFT using web3.py

What You've Accomplished

Resources for Continued Learning:

Part 6: ERC-20 Tokens with web3.py - Balances, Transfers, and Approvals

What Are ERC-20 Tokens? The Foundation of Digital Assets

Key ERC-20 Functions We'll Explore

Read Functions (View State)

Write Functions (Change State)

Building Your Own ERC-20 Token

Deployment Steps (using Remix IDE to Ganache):

Interacting with Your ERC-20 Token using web3.py

For DEX Integration Flow (e.g. Uniswap):

What You've Accomplished

Useful Resources:

Part 5: The Backbone of Blockchain Interoperability - Understanding Standards

What Are Blockchain Standards?

Blockchain Standards Work Similarly...

Why Standards Are Essential for Blockchain

1. Interoperability: The Foundation of DeFi

2. Composability: "Money Legos"

3. Developer Efficiency

4. Superior User Experience

5. Ecosystem Growth Acceleration

How Are Blockchain Standards Created?

The EIP Process

EIP Categories

What is ERC?

Essential Blockchain Standard Categories

1. Token Standards

2. Interface Standards

3. Identity & Naming Standards

4. Governance Standards

Standards in Action with web3.py

ERC-20 Interaction Example

Standards Enable Innovation

1. The Operator Account (`ProtocolVault`)

`update_protocol` (Safety Vault Requirement Check)

`calculate_k_pool (`Kamino Pool Valuation)

`calculate_total_assets` (Net Available Capital)

`ktoken_to_burn (`Redemption Calculation)

2. The Employee Account (`StaffAccount`)

`claimable_salary`

3. Kamino's Reserve Account (`Reserve`)

4. Rebalance (R`ebalance`)

5. Staff Initialisation (S`taffInit`)

Interacting with Your NFT using `web3.py`

Interacting with Your ERC-20 Token using `web3.py`