Site Name Blog

x402 Deep Dive: A Payment Standard for the Internet

2025-10-30T09:15:20.030Z

x402 is a new payment standard that enables micro payments on the web by leveraging blockchain technology. It leverages the existing 402 Payment Required status code to require payment before serving a response and uses crypto-native payments for speed, privacy, and efficiency, enabling micro payments.

In this article, you will explore how x402 works for programmatic services and how you can integrate it into your existing workflows using a simple Express app as an example.

How Does x402 Work?

Every x402 workflow has three main components:

The buyer or client
The seller or server
The facilitator

The Seller

In an x402 workflow, the seller, or server, refers to the entity that has paywalled a service using the x402 standard. The seller must define the payment requirements for the resource, including the amount, the blockchain network, the payment asset, and the payment destination (a wallet address).

Note that x402 only supports payment assets that implement the EIP-3009 (transferWithAuthorization) method, for example, USDC. This is because x402 sends a signed payment in a request header, so it needs a token that lets a relayer submit that signature on-chain without first setting allowances, and EIP-3009 transferWithAuthorization is the standard that enables exactly this.

The Buyer

In an x402 workflow, the buyer/client refers to the entity trying to access a paywalled service. A client can either be manually operated by a human, programmatically operated on behalf of a user, or autonomously operated using an AI agent.

Regardless of the client type, the flow remains the same. After initiating a request to a 402 Payment Required protected endpoint, they read the payment details provided by the seller, construct a valid payment payload, and retry the request with an X-PAYMENT header containing the signed payment payload.

The Facilitator

Although optional, a facilitator removes a lot of the overhead associated with verifying and settling payments between sellers and buyers.

In a direct peer-to-peer x402 flow, the buyer requests a protected endpoint and receives a 402 Payment Required response with payment details (amount, blockchain network, wallet address). The buyer then creates and submits a blockchain transaction and retries the request with a X-PAYMENT header containing the transaction proof.

The seller must independently verify the payment on the blockchain before granting access. This requires both parties to handle blockchain interactions directly, including transaction submission and on-chain verification.

A facilitator acts as a trusted intermediary for payment verification and settlement. Instead of sellers querying the blockchain directly, the facilitator provides a verification service that handles transaction broadcasting, confirmation monitoring, and issues cryptographically signed payment receipts.

There are several facilitators available today, such as:

CDP’s facilitator on Base mainnet, which offers fee-free USDC settlement on Base mainnet.
PayAI’s facilitator on Solana, Base, Polygon, and more.
Custom facilitators such as x402-sovereign by dhai.eth.

The entire x402 flow is stateless. Clients do not need to manage accounts, credentials, or session tokens beyond their crypto wallet, and servers do not need to manage client identities or maintain session state.

Everything is handled per request, making x402 well-suited for one-time or occasional access patterns, but potentially impractical for flows requiring frequent, continuous access to the protected resource due to per-request payment costs.

How to Use x402 in Your Apps?

This section covers how you can use x402 in your current workflow.

For this tutorial, we are going to use x402-express and x402-fetch to implement the flow for the seller and the buyer, respectively, because they already abstract most implementation details, allowing you to get started immediately. We are also going to x402-sovereign as our facilitator because it doesn't require any setup or API keys like CDP’s or PayAI’s.

Using x402 as Seller

To add an x402 paywall to a resource on an Express server or a similar server, you need to add the following packages to your existing app.

x402-express: Middleware for Express that handles x402 payment verification and responds with 402 Payment Required when payment is missing or invalid.
viem: TypeScript library for Ethereum interactions, used to verify blockchain transactions and interact with smart contracts.
x402-sovereign/core

Install them by running the command below:

npm install @x402-sovereign/core viem x402-express

You also need an EVM private key that will receive payments and pay gas.

🚨

Ensure you store your private key in an .env file that is not tracked by version control!

Next, you need to initialize your facilitator using your private key and specifying your supported networks:

import { Facilitator } from "@x402-sovereign/core";

const facilitator = new Facilitator({
  evmPrivateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
  networks: [baseSepolia, sepolia],
});

The code block above initializes a custom facilitator using x402-sovereign supporting base sepolia and sepolia.

x402-sovereign exposes an express adapter that you can register as a middleware to mount the facilitator endpoints your server will call for verification and settlement. Like so:

import { createExpressAdapter } from "@x402-sovereign/core";

createExpressAdapter(facilitator, app, "/facilitator");

This mounts your local facilitator API onto your Express app under the /facilitator path. It registers three routes:

GET /facilitator/supported
POST /facilitator/verify
POST /facilitator/settle

It then forwards those requests to facilitator.handleRequest({ method, path, body }): /supported returns the facilitator’s capabilities and the networks you configured, /verify decodes the X-PAYMENT header and validates the EIP-712 signature, amount, asset, payTo, resource URL, chain ID, and time/nonce, and /settle Re-verifies and submits the EIP-3009 transferWithAuthorization on chain using your evmPrivateKey, returning success and a txHash. The adapter adds no business logic or auth; it just relays the status and body from the facilitator, or returns a 500 if an error occurred.

After configuring your facilitator, you can use the paymentMiddleware provided by x402-express to register the routes you want to protect, along with their associated prices.

For example:

app.use(
  paymentMiddleware(
    PAY_TO,
    {
      "/add-badge": {
        price: "$0.01",
        network: "base-sepolia",
        config: {
          description: "Grant Badge",
        },
      },
      "/premium/*": {
        price: "$0.10",
        network: "base-sepolia",
        config: {
          description: "Access to premium content",
        },
      },
    },
    {
      url: `${BASE_URL}/facilitator` as `${string}://${string}`,
    }
  )
);

The middleware will return 402 Payment Required with a challenge (image below) when the request is missing/invalid, and will call your handler once a valid X-PAYMENT header is supplied.

You can find the full implementation for this section in this GitHub repository.

Using x402 as Buyer

To programmatically access routes protected by x402, you need the x402-fetch package, which provides utilities to wrap standard fetch with automatic x402 payment handling, including signature creation and payment proof construction.

You also need an EVM private key to sign and submit payments.

🚨

Store it securely in your .env file that is not tracked by version control!

To make requests to x402-protected endpoints, you need to create a signer for your target network and wrap the standard fetch function with payment capabilities:

import { 
  wrapFetchWithPayment, 
  createSigner, 
  type Hex 
} from "x402-fetch";

const privateKey = process.env.PRIVATE_KEY as Hex | string;
const signer = await createSigner("base-sepolia", privateKey);
const fetchWithPayment = wrapFetchWithPayment(fetch, signer);

The createSigner function initializes a signer for the specified network using your private key. The wrapFetchWithPayment function returns an enhanced fetch that automatically handles the x402 payment flow.

Now you can use fetchWithPayment just like the standard fetch function:

const response = await fetchWithPayment(`${endpointBaseUrl}/add-badge`, {
  method: "GET",
});

const body = await response.json();
console.log(body);

When you request a protected endpoint, fetchWithPayment automatically detects the 402 Payment Required response, reads the payment requirements from the challenge, constructs and signs the payment proof, and retries the request with the X-PAYMENT header. From your perspective, it works seamlessly like a regular fetch call.

Optionally, you can access payment details from the response headers:

import { decodeXPaymentResponse } from "x402-fetch";

const paymentResHeader = response.headers.get("x-payment-response");

if (paymentResHeader) {
  const paymentResponse = decodeXPaymentResponse(paymentResHeader);
  console.log(paymentResponse);
}

The x-payment-response header contains information about the payment transaction, including the transaction hash and settlement status.

You can find the full implementation for this section in this GitHub repository.

Conclusion

The x402 standard provides practical developer tools for implementing ERC-8004, the protocol specification for blockchain-based HTTP payments. By abstracting the complexity of EIP-712 signatures and EIP-3009 settlements, x402 enables truly stateless, pay-per-use APIs without traditional authentication.

To learn more about the underlying protocol, visit the ERC-8004 proposal. To explore the x402 ecosystem, check out x402.org.

Using Arweave for AI Provenance

2025-10-30T08:46:43.624Z

The so called AI slop all over the internet is getting less sloppy.

NBC News

We're living through an extraordinary moment in history. The rapid evolution of generative AI has unleashed an unprecedented creative boom. These tools have democratized content creation in ways unimaginable just a few years ago. With a few prompts, anyone can whip up stunning images or immersive videos, no special training required.

AI is remarkable. AI is empowering. AI is also terrifying…

Generative models are now producing images, videos, and text at a scale never seen before, and lately, they can be indistinguishable from human-made content. From social media feeds to news articles, AI’s creative “fingerprints” are everywhere. Photorealistic portraits, cinematic visuals, and engaging essays can all be churned out by AI in minutes.

While it is empowering a single person with a laptop to achieve what once took teams, it poses a new question: How can we trust what we see and hear?

What's Real?

Recently, how often has your mum shown you an image or a reel and asked you if it’s real or AI-generated?

The question is popping up more and more, and not without reason. As generative AI improves its output quality, the lines between reality and fiction continue to blur.

Remember that image of Pope Francis walking on the streets of the Vatican in a designer coat fooled countless people online into thinking it was real?

Photo: r/midjourney subreddit

Or when AI tools mimicked Studio Ghibli's distinctive art style?

Photo: ghibliai.ai

AI-generated content is flooding the internet, mimicking Hayao Miyazaki's painstaking hand-drawn aesthetic, appearing everywhere from fan art communities to brand moodboards and beyond. Even I wasn't immune to trying it out.

While I do not want to get into the ethical discussion of replicating an art style in this article, I do feel that had anyone generated an entire book or film in this style, we might not have been able to tell it apart from the originals. There’s real concern about authenticity and trust in this AI-saturated landscape. The stakes can range from simple confusion to serious deception. Misleading AI-generated media can spread misinformation. I believe the trust in what we consume online is at stake. And we need a layer of transparency that helps us distinguish AI-generated media from authentic media.

Proof of Origin

What if instead of trying to detect AI content after it's created, we could establish verifiable proof of origin at the moment of creation?

This is where blockchain technology could come in. They are essentially ledgers that can store tamper-proof records, with multiple copies distributed across many nodes worldwide. If there's one thing blockchains are designed to excel at, it's preserving an immutable trail of information that anyone can verify.

What if every AI-generated image, video, or text came with an unforgeable “receipt” describing how it was created?

These receipts can serve as publicly auditable proofs of the origins of any AI-generated content.

Arweave and HyperBEAM

While I am yet to explore more technologies, something I will continue to do over the coming days, my familiarity with @ArweaveEco and HyperBEAM makes them potential good fits for this solution.

HyperBEAM, built on the @aoTheComputer's spec, is a decentralized operating system that enables verifiable computation over HTTP. Inspired by the Erlang actor model, every interaction is handled as a message.

And the cool part?

It uses RFC 9421, the latest HTTP message signature standard.

Blockchains, for the most part, are known to be walled gardens that require specialized services, like oracles, to communicate with the traditional web. So, a system that can do so by default opens up very interesting possibilities.

HyperBEAM includes devices that enable API requests with cryptographic receipts of those calls. In theory, every AI generation request could produce an immutable receipt stored permanently on Arweave, creating an unalterable record of origin.

How Could it Work?

Imagine this workflow:

You generate an image with DALL-E.
The API request is signed using RFC 9421's HTTP message signature protocol.
The signature captures the request parameters, timestamps, the requester's identifier, and the model used.
HyperBEAM's devices process this request and generate a cryptographic receipt.
The receipt gets stored permanently on Arweave.

Now the generated image carries verifiable provenance. Anyone can trace it back to its moment of creation, verify who requested it, which AI model produced it, and when it was produced. The receipt is immutable. No one can alter this historical record. By adding cryptographic signatures to standard web requests, users can get a verifiable trail of truth. While this system doesn't prevent AI generation, it helps us embrace the benefits by establishing accountability and attribution.

What are the Use Cases?

Verification of news or user-generated content: During breaking events like footage of natural disasters, celebrity sightings, etc., provenance lets platforms and audiences confirm whether a clip came from a verified source or an AI before it spreads.
Protecting artists & brands: Creators and studios can register originals. Style-inspired pieces carry distinct receipts, enabling faster, fairer attribution, licensing, and takedown decisions.
Legal evidence: Courts handling deepfake cases could verify the authenticity of digital evidence through blockchain-backed provenance trails.

In general, while institutions like the Coalition for Content Provenance and Authenticity (C2PA) standard embed cryptographic signatures and metadata into digital assets, it has its limitations. Integrating this with blockchain technology could make these even more robust and perpetually accessible.

Why Does This Matter Now?

We're at an inflection point. AI content generation is accelerating exponentially. By the end of 2025, estimates suggest 8 million deepfakes will be shared online, up from 500,000 in 2023. Europol estimates 90% of online content may eventually be generated synthetically.

Trust could collapse without provenance. When we can't distinguish real from fake, we lose our shared basis for truth. Blockchain-based provenance isn't a silver bullet. It requires adoption by AI platform providers, integration into content creation tools, and cultural acceptance of transparency over anonymity.

The Bottom Line

AI has genuinely been transformative. It's democratizing content creation, enabling new forms of expression, and augmenting human creativity in remarkable ways.

We shouldn't fear this technology, but we should be wary and establish guardrails while it’s still young. Data provenance is one.

We have infrastructure in place. HyperBEAM can provide signed receipts of API calls, which can then be stored on Arweave as an immutable proof of origin. At the very least, these give a path to experiment and establish a baseline for trust in this age of AI.

If you think this post might resonate with someone you know, please share it with them!

An Introduction to Force Inclusion

2025-10-21T14:32:00.132Z

In these last few years, layer two blockchains (L2) have become central to Ethereum's scaling efforts. L2s are fast, cheap, and inherit Ethereum's strong security guarantees. Ethereum serves as the settlement layer, and L2s serve as the execution layer. This is great.

It is important to pause here, though, and ask:

What does it mean that these L2s inherit Ethereum's security guarantees?
What does it mean for an L2 to be secure?

This article won’t cover all the different L2 security details, but it will discuss one of the most important ones: censorship resistance.

What is Censorship Resistance?

An ideal L2 should be censorship-resistant. This means that no single entity or group (including the network operators, especially the network operators) should be able to prevent users from accessing the network or using its services.

Most L2s use highly centralised sequencer sets for speed, though. This is the usual lifecycle of an L2 transaction. For example, you send some ETH to a friend on Base:

It is not hard to spot that there is a potential single point of failure in this system. The sequencer can censor your transaction and refuse to include it in the next batch.

This is not good.

But the cool thing about real L2s is that this is not the end of the story. They are designed to protect users in exactly this scenario.

What is Force Inclusion?

When you suspect that an L2 sequencer is misbehaving, you can bypass it entirely and get your transaction included anyway. Whether the sequencer likes it or not, it does not have a choice.

This sequencer bypass is called force inclusion and looks like this:

How is Force Inclusion Possible?

In very simple terms, an Ethereum L2 is just a sophisticated set of smart contracts living on Ethereum L1. When you send a transaction on an L2, it is eventually posted to one of these smart contracts on Ethereum L1. The transaction is only considered truly 'final' once that happens. Unless you are using an optimistic rollup, in which case the finality can take up to 7 days.

This is why L2s inherit Ethereum's security. The source of truth for L2s is Ethereum L1, not the L2 sequencers or L2 nodes. The sequencer abstracts away the complexity of creating a valid L2 transaction and posting it properly to Ethereum. Any user can do this, too, but it is obviously more complicated.

As an educational exercise, let's explore how you can actually send a transaction to an L2 without using the sequencer.

Trying Out Force Inclusion

Most major L2s support force inclusion. For this example, we will aim to get a transaction force-included on Base mainnet. To keep things simple, we will attempt to send some ETH from one address to another, but the same methods work for transactions of any level of complexity.

I will be running a simple Bun script here. Let's initialize the project and install the one dependency we will need:

bun init

bun add ethers dotenv

We will also need a wallet's private key to send our transaction out. Note that this wallet needs to be funded on both Ethereum L1 and Base L2. We need ETH on L1 to pay the gas for the L1 transaction, and on L2 to pay for the ETH transfer.

🚨

Use a throwaway dev wallet for this exercise. Do not use a wallet you use for anything else.

Create an .env file and paste the private key there:

WALLET_PRIVATE_KEY=0x...

Let's open up index.ts and start setting up the script now.

import { ethers } from "ethers";
import "dotenv/config";

const l1Provider = new ethers.JsonRpcProvider("https://eth.llamarpc.com");
const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY!, l1Provider);

const portal = new ethers.Contract(
  "0x49048044D57e1C92A77f79988d21Fa8fAF74E97e", // OptimismPortal contract address on Ethereum (used by Base)
  [
    "function depositTransaction(address to,uint256 value,uint64 gasLimit,bool isCreation,bytes data) payable",
  ],
  wallet
);

Base is an OP Stack rollup. This means that it uses a similar smart contract structure to Optimism and other OP Stack rollups.

Remember how we discussed earlier that users have the ability to send transactions to one of the rollup contracts on Ethereum if they want to get a transaction force-included? This smart contract is called OptimismPortal for Base. To put things very simply, any valid L2 transactions deposited to this contract will be force-included on Base L2. This mechanism is slightly different from other rollup stacks like Arbitrum, but the core idea is the same.

If you are curious, you can check out the contract on Etherscan.

You might have also noticed the depositTransaction function signature that we added to our contract initialization code. This is the function we will be calling to deposit our transaction to the rollup contract.

The next step is to construct the actual transaction that we wish to send.

const to = "0x0ED6Cec17F860fb54E21D154b49DAEFd9Ca04106";
const value = ethers.parseEther("0.001");
const gasLimit = 200000n; // conservative
const data = "0x";

const tx = await portal.depositTransaction(
  to,
  value,
  gasLimit,
  false,
  data,
  { value } // pay ETH
);

console.log("L1 tx hash:", tx.hash);

We need to specify five properties:

to: This is the address of the L2 wallet that we want to send the ETH to. If you were calling a smart contract, this would be the address of the contract you want to call.
value: This is the amount of ETH we wish to send to the L2 wallet.
gasLimit: This is the maximum amount of gas we are willing to pay for the transaction. Libraries like viem provide helpers that can calculate this for you. For now, we will use a conservative estimate.
isCreation: This is a boolean value that indicates whether the transaction is creating a new contract or not. If you are sending ETH to an existing contract, this should be set to false. We have set this to false.
data: The calldata for the transaction. Since we are doing a simple ETH transfer, we can leave this as 0x. If you were interacting with a smart contract, this would be the encoded function call data.

Notice how we are not interacting with any Base RPC endpoints or contracts at all. Everything is being sent to Ethereum directly.

💡

Check that the private key you provided in the .env is funded on both L1 and L2, and check the receiving address on L2 (the to field). This is the address that will receive the funds on Base.

For reference, you can find the complete code on GitHub.

Run the script, and check the transaction hash on Etherscan:

bun run index.ts

Once the transaction is confirmed on L1, you might need to wait around 2 epochs (~13 minutes) for the Ethereum chain to be finalised before the transaction is included in an L2 block.

After waiting, you should see a transaction pop up on Base L2 for the receiving address. You should receive the exact amount of ETH that you specified in the value field.

Congratulations!

You just sent some ETH from one address to another on an Ethereum L2 without interacting with the L2 sequencer.

Conclusion

I hope this article served as a very basic primer on why force inclusion is important and how you can use this security feature yourself if need be.

I am currently working on an SDK around this with some friends to make similar rollup security features more accessible to developers. You can check it out on GitHub!
Also, I’m currently looking for my next role in crypto. My X DMs are open, hmu!

An Introduction to Blockchain RPC Nodes

2025-10-21T14:31:21.360Z

A blockchain is a peer-to-peer (P2P) network of nodes that maintains a shared ledger. Every node communicates with other nodes in the network using specialized P2P protocols to verify blocks, transactions, store state, etc.

When you’re building an app on a blockchain, you need a way to communicate with these nodes to read the current state of the blockchain (balances, contract/account data, logs) and write a new state.

However, direct P2P communication is impractical because node-to-node communication is optimized for consensus and gossip, not for app developers. This is because they involve a lot of complex processes that browsers and typical backends aren’t designed to handle.

Remote Procedural Call (RPC) nodes exist to abstract this complexity and provide a stable HTTP/WebSocket-friendly way to read and write blockchain data.

What is an RPC Node?

An RPC node is a blockchain node configured to expose this developer-friendly API. Behind the scenes, it syncs the chain, validates data, and “gossips” with peers; to you, it presents clear methods (read state, submit signed transactions, subscribe to updates) accessible via an RPC endpoint (the URL of the API).

RPC is a communication protocol that allows a program on one computer to execute a function on a different computer as if it were a local call. On blockchains, this commonly appears as JSON-RPC over HTTP or WebSocket so that you can call methods like getBalance(address) which returns the balance of an address without handling low-level networking.

For example:

curl -X POST https://mainnet.infura.io/v3/YOUR_PROJECT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
      "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
      "latest"
    ],
    "id": 1
  }'

The request above fetches the address’s balance (in Wei) using an RPC provider like Infura via an Ethereum JSON-RPC endpoint. In practice, apps use libraries like viem, ethers.js, or web3.js to talk to RPC endpoints.

How do RPC Nodes Work?

RPC nodes are normal blockchain nodes with an exposed API surface. The node maintains chain state (syncs blocks, executes transactions, stores results). The RPC layer maps your requests to the right internal components (state/execution, transaction pool, or subscription engine).

💡

The mechanisms explained below depict how RPC nodes on the Ethereum mainnet behave. It can vary from blockchain to blockchain.

Reading Data From a Blockchain

For a read (e.g., “get balance” or a contract view), the node selects the state at the block tag (latest, pending, safe, finalized) you asked for, or a specific block number. If the method requires execution (for example, an eth_call against a contract), the node runs the call against a sandboxed state at that height, without changing the chain. It then serializes the result and returns it.

Writing Data to a Blockchain

For a write (i.e., submitting a signed transaction), the node validates the format and signature (tx type, chainId, nonce, gas limits/fees, optional access list). If valid, your request enters the mempool and is “gossiped” to peers. A block producer includes it, and after its execution, you can query receipts, logs, and confirmation depth.

Subscribing to Events of a Blockchain

Over WebSocket, Ethereum supports eth_subscribe channels such as:

newHeads (new block headers)
logs (filtered by address/topics)
newPendingTransactions

The node manages buffers/backpressure; clients should handle reconnects and resume from the last seen block number to stay consistent.

How to Use an RPC Node?

To use an RPC node, you can either run your own private RPC node, use a public RPC node, or use an RPC node provider.

Hosting Your Own RPC Node

If you need overall control over your own RPC node, you can install and run blockchain clients like Geth, Nethermind, or Reth on your own hardware or virtual server and enable RPC on them.

💡

Running your own node requires a lot of maintenance on your end and is best for teams with special needs.

Using a Public RPC Node

Most blockchains provide free public RPC endpoints that allow anybody to use RPC nodes. Due to their easy accessibility, they are usually overloaded and rate-limited, making them ideal for small DApps and testing. Additionally, they may not offer WebSocket support.

Examples of popular public RPC nodes include the following:

Chain	Provider	RPC Endpoint
Ethereum	PublicNode	https://ethereum-rpc.publicnode.com
Solana (Mainnet-beta)	Anza (Solana Labs)	https://api.mainnet-beta.solana.com
BNB Smart Chain	BNB Chain (official)	https://bsc-dataseed.bnbchain.org
Sui (Mainnet)	Mysten Labs	https://fullnode.mainnet.sui.io:443

Using an RPC Node Provider

This is the most popular option for most developers because using RPC node providers is cheaper than running your own RPC node, and you can scale your configuration as your usage increases. To use an RPC provider, you need to sign up on their platform, choose a plan, and start querying their endpoint. Some popular RPC Node providers include Alchemy & QuickNode.

📡

Another interesting RPC provider is the D_D Cloud, which is built on the POKT Network and gives you access to 60+ chains with unbeatable uptime. You can join the D_D Cloud waitlist here.

Conclusion

You can think of RPC nodes as the API layer of the blockchain. They abstract all the complexities associated with P2P communication between a node and a Dapp and expose a friendlier UI.

You can access an RPC node via paid providers (often with free tiers), community/public endpoints, or by running your own dedicated node. Whichever route you choose, decide based on your needs for reliability, latency, and cost, and data/privacy requirements.

Working With Solana Tokens Using Native Rust

2025-10-21T14:30:40.478Z

Tokens represent money-like assets, utility (such as governance or access), rewards and points, game items, tickets, and more. Most tokens on Solana follow the SPL token standard or Token-2022 with extensions, which define how tokens are created, transferred, and burned.

This article covers how tokens work on Solana and how you can use them in your program. The examples in this article are in native Rust, but the concepts can be applied to any framework or library (Anchor, Pinocchio, Steel).

How do Solana Tokens Work?

Every token on Solana has a mint account. A mint account defines key information about the token, such as the decimals, authority (who can mint and optionally freeze), total supply, etc. However, the mint account only defines the token; it doesn’t store it.

Token decimals describe the asset’s fractional precision. If a mint has d decimals, then 1 token = 10^d base units. Because on-chain programs use integers only to keep consensus deterministic (floating-point can round differently across machines), wallets and dapps convert to/from base units by multiplying or dividing by 10^d. For example, many fiat-like tokens (e.g., USDC) use six decimals, so 1 USDC = 1,000,000 base units.

Tokens can exist as fungible or non-fungible (NFTs). Fungible tokens typically use decimals like 6 or 9 for divisibility, while NFTs use 0 decimals and a supply of 1 (or small editions).

The token balances live in associated token accounts (ATAs). ATAs are deterministically derived from a (owner, mint, token_program_id) tuple. Names, symbols, and logos aren’t in the mint or token account. UIs read them from a Metaplex Token Metadata account linked to the mint.

Most resources on the web currently cover creating tokens on the client side with a CLI or SDK because it’s simpler, cheaper (no CPI), and fits one-off user-issued tokens or NFTs.

This guide takes the other path, creating mints on-chain inside your program using PDAs and program-controlled authorities. That approach is crucial when the token is core to protocol safety or pricing, e.g., AMM LP shares, vault/receipt tokens, etc. As such, the examples in this tutorial are helper functions that can be part of a bigger program, not a standalone one.

Setting Up a Development Environment

To follow along with this tutorial, you will need to set up a minimal Native Rust program.

Start by running the command below to create a new project:

cargo init token-mints --lib

Then add the following crates by running the command below:

cargo add borsh@1.5.7 && \
cargo add solana-program@2.3.0 && \
cargo add solana-system-interface@1.0.0 --features bincode && \
cargo add spl-associated-token-account@7.0.0 --features no-entrypoint && \
cargo add spl-token@7.0.0 --features no-entrypoint

The crates you added above include:

borsh – Deterministic binary serialization/deserialization for your program/account data. Commonly used to (de)serialize instruction payloads and account state.
solana-program: types like Pubkey, AccountInfo, ProgramResult, entrypoint glue, sysvars, and helpers to build/parse instructions.
solana-system-interface (+ bincode feature) – Stable interface types/IDL for the System Program (create accounts, transfers, etc.).
spl-associated-token-account (no-entrypoint) – Instruction builders and CPI interface for the Associated Token Account (ATA) Program (create/find ATAs).
spl-token (no-entrypoint) – Instruction builders, state types, and CPI interface for the SPL Token Program (mint, transfer, burn, etc.).

Note: Ensure you install the exact versions in the command above, else this may not work as expected.

Creating and Initializing a Token Mint

In this section, you’ll build a small helper, create_and_init_mint, that allocates a mint account as a PDA, then initializes it so your program (via a PDA) controls minting. We’ll set the freeze authority to None to keep the asset non-custodial by default.

The function will accept the following inputs:

Accounts:
- Payer (signer, writable): funds rent and signs the create account instruction.
- Mint (PDA, writable, uninitialized): the account to become your mint.
- System Program*:* required by the system create_account.
program_id: your program ID.
token_decimals: u8
mint_authority: Pubkey (recommend a program PDA)
mint_seeds: &[&[u8]] (the PDA seeds/bump for the mint)

Before you proceed, ensure that you have the following imports at the top of your file:

use solana_program::account_info::{next_account_info, AccountInfo};
use solana_program::entrypoint::ProgramResult;
use solana_program::program::{invoke, invoke_signed};
use solana_program::program_error::ProgramError;
use solana_program::program_pack::Pack;
use solana_program::pubkey::Pubkey;
use solana_program::rent::Rent;
use solana_program::sysvar::Sysvar;

use spl_token::id as spl_token_id;
use spl_token::instruction as token_instruction;
use spl_token::state::{Account as SplAccount, Mint as SplMint};

Note that the imports from spl_token are renamed to avoid conflicts with packages from solana_program.

Creating the Token Mint

To create the mint, first, you allocate the mint account as a program-derived address (PDA) and set its owner to the SPL Token program. This ensures that, after creation, only the token program itself can mutate the mint’s data.

Next, you set the mint authority to a PDA controlled by your program, so any future issuance must come through your on-chain logic (you’ll sign CPIs with invoke_signed).

You then intentionally leave the freeze authority as None, avoiding a built-in backdoor that could freeze user accounts. Finally, you choose the decimals explicitly to set the asset’s precision up front (e.g., 6 for fiat-like tokens, 9 for Solana-style precision, 0 for NFTs).

Like so:

pub fn create_and_init_mint(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    mint_authority: &Pubkey,
    mint_seeds: &[&[u8]],
    token_decimals: u8,
) -> ProgramResult {
    let acc_iter = &mut accounts.iter();

    //payer (signer), mint (writable), system program
    let payer = next_account_info(acc_iter)?;
    let token_mint = next_account_info(acc_iter)?;
    let system_program = next_account_info(acc_iter)?;

    if !payer.is_signer {
        return Err(ProgramError::MissingRequiredSignature);
    }

    if !token_mint.is_writable {
        return Err(ProgramError::InvalidAccountData);
    }

    // Ensure the passed mint is exactly the PDA we expect for these seeds.
    let expected = Pubkey::create_program_address(mint_seeds, program_id)
        .map_err(|_| ProgramError::InvalidSeeds)?;
    if *token_mint.key != expected {
        return Err(ProgramError::InvalidSeeds);
    }

    let space = SplMint::LEN as u64;
    let lamports = Rent::get()?.minimum_balance(space as usize);

    invoke_signed(
        &solana_system_interface::instruction::create_account(
            &payer.key,
            &token_mint.key,
            lamports,
            space,
            &spl_token_id(),
        ),
        &[payer.clone(), token_mint.clone(), system_program.clone()],
        &[mint_seeds],
    )?;

Now, you have created the token mint. Next, you will initialize it.

Initializing Token Mints

To initialize the token mint, you need to invoke the initialize_mint2 instruction from the SPL token program. Pass the SPL program ID, the mint account’s public key, the mint_authority, the freeze authority, and the decimals into the instructions and invoke the instruction with the token mint account.

Like so (this snippet is part of create_and_init_mint):

    let initialize_ix = token_instruction::initialize_mint2(
        &spl_token_id(),
        token_mint.key,
        mint_authority,
        None,
        token_decimals,
    )?;

    invoke(&initialize_ix, &[token_mint.clone()])?;

    Ok(())

  }

There’s an alternative to the initialize_mint2 instruction, which is the initialize_mint function. Both set the same mint fields (decimals, mint authority, freeze authority).

The difference is in the required accounts:

initialize_mint2 does not require the Rent sysvar; you pass only the mint account in the CPI account list.
initialize_mint requires the Rent sysvar and will read it during initialization.

After initialization, the mint’s total supply is 0. The SPL Token program does not enforce a cap; your supply policy is up to you.

You create supply by calling mint_to_checked from your mint authority (usually a PDA) into a token account (often a treasury ATA). However, if you want a fixed supply, mint the full amount and then revoke the mint authority by setting it to None (This process is irreversible).

Here’s an example:

// Mint initial supply to a treasury ATA, then lock the mint.
let amount_base = ui_amount
    .checked_mul(10u64.pow(token_decimals as u32))
    .ok_or(ProgramError::InvalidArgument)?;

let ix = token_instruction::mint_to_checked(
    &spl_token_id(),
    token_mint.key,
    treasury_ata.key,
    mint_authority,      // your PDA signs via invoke_signed
    &[],
    amount_base,
    token_decimals,
)?;
invoke(&ix, &[token_mint.clone(), treasury_ata.clone(), /* + authority account */])?;

// Later, make supply fixed:
let ix_disable = token_instruction::set_authority(
    &spl_token_id(),
    token_mint.key,
    None, // new authority = None → revoke
    spl_token::instruction::AuthorityType::MintTokens,
    mint_authority,
    &[],
)?;
invoke(&ix_disable, &[token_mint.clone(), /* + authority account */])?;

Now, you have created and initialized the token mint. Next, you will make associated token accounts for the mints.

Creating an Associated Token Account

For any user to hold the token you just minted and initialized, they have to own an ATA for the mint. An ATA is a deterministic address derived from an (owner, mint, token_program_id) tuple, so wallets and programs can compute it and fetch that single account.

When creating ATAs, decide who pays the rent to initialize the account. You can sponsor creation from your program (great onboarding, but costs scale with users), or require the user to fund it themselves (adds a signature step and a bit of friction, but controls your spend). Anyone may pay the fee; payer and owner do not have to be the same, and the payer gains no control over the account.

To create an ATA, invoke the create_associated_token_account_idempotent instruction from the spl_associated_token_account::instruction crate with the following accounts (in the same order): payer, owner, ATA account, token mint account, token program account, system program account.

Like so:

use spl_associated_token_account as ata;

pub fn create_ata_for(accounts: &[AccountInfo]) -> ProgramResult {
    let acc_iter = &mut accounts.iter();

    let payer = next_account_info(acc_iter)?; //pays the fees for account creation
    let owner = next_account_info(acc_iter)?; //Owner of the ATA
    let ata_acc = next_account_info(acc_iter)?;
    let token_mint = next_account_info(acc_iter)?;
    let token_program = next_account_info(acc_iter)?;
    let system_program = next_account_info(acc_iter)?;

    // Derive the expected ATA address and compare
    let expected_ata = ata::get_associated_token_address_with_program_id(
        owner.key,
        token_mint.key,
        &spl_token_id(),
    );

    // Sanity check: is the passed ATA the one we expect?
    if ata_acc.key != &expected_ata {
        return Err(ProgramError::InvalidArgument);
    }

    // Payer must sign
    if !payer.is_signer {
        return Err(ProgramError::MissingRequiredSignature);
    }

    // Create the ATA (idempotent)
    let ata_instruction = ata::instruction::create_associated_token_account_idempotent(
        payer.key,
        owner.key,
        token_mint.key,
        &spl_token_id(),
    );

    // Invoke the ATA creation instruction
    invoke(
        &ata_instruction,
        &[
            payer.clone(),
            ata_acc.clone(),
            owner.clone(),
            token_mint.clone(),
            system_program.clone(),
            token_program.clone(),
        ],
    )?;

    Ok(())
}

Now you can create ATAs for your mints. Next, you will learn how to burn tokens from the ATAs.

Burning Tokens

Burning destroys tokens from a specific token account and reduces the mint’s total supply by the same amount. The SPL Token program enforces that only the token account owner (or an approved delegate) may burn from that account; you do not need the mint authority.

To burn tokens, invoke the spl token programs burn_checked instruction with the following accounts (in the same order): token mint account, ATA owner account, ATA.

Like so:

pub fn burn_user_tokens(accounts: &[AccountInfo], amount_ui: u64) -> ProgramResult {
    let acc_iter = &mut accounts.iter();

    // 0 mint, 1 owner(signer), 2 token_account(ATA), 3 token_program
    let mint_account = next_account_info(acc_iter)?;
    let owner_account = next_account_info(acc_iter)?; // authority, must sign
    let ata_token_acc = next_account_info(acc_iter)?;

    if !owner_account.is_signer {
        return Err(ProgramError::MissingRequiredSignature);
    }

    // Sanity: token account belongs to owner and matches mint
    let token_account = SplAccount::unpack(&ata_token_acc.try_borrow_data()?)?;
    if token_account.mint != *mint_account.key || token_account.owner != *owner_account.key {
        return Err(ProgramError::InvalidAccountData);
    }

    // Derive base units using mint decimals
    let mint = SplMint::unpack(&mint_account.try_borrow_data()?)?;
    let decimals = mint.decimals;
    let amount_base = amount_ui
        .checked_mul(10u64.pow(decimals as u32))
        .ok_or(ProgramError::InvalidArgument)?;

    // Burn (checked) — accounts: [token_account, mint, authority]
    let burn_ix = token_instruction::burn_checked(
        &spl_token_id(),
        ata_token_acc.key,
        mint_account.key,
        owner_account.key,
        &[],
        amount_base,
        decimals,
    )?;

    invoke(
        &burn_ix,
        &[
            ata_token_acc.clone(),
            mint_account.clone(),
            owner_account.clone(),
        ],
    )?;

    Ok(())
}

Conclusion

With the core pieces in place, mints that define the assets, ATAs that hold balances, and a burn mechanism to control supply. You’ve learnt how to create a mint as a PDA, initialize it with explicit decimals and authorities, derive and fund ATAs, mint and transfer in base units, and burn safely.

With these primitives, you can ship payments, points, or NFTs end-to-end in native Rust.

You can find the code examples with associated tests in this GitHub repository. This is part one of a two-part series; the next part will cover Token-2022 extensions and hooks.

To get notified when it drops, follow me on X :).

BuildBear Tutorial: Cross-Chain Bridge

2025-10-07T11:37:38.946Z

This is post was written by @0xJustUzair

BuildBear is a specialized platform for DApp development and testing. Developers can create a personalized private testnet sandbox for various EVM and EVM-compatible blockchain networks.

Key Features

Access a private faucet for unlimited minting of native and ERC-20 tokens.
Experience lightning-fast transactions, completing in under three seconds.
Debug transactions effortlessly within your sandbox using the built-in explorer and transaction tracer.
Leverage real-time testing and debugging tools, along with many other advanced features.

Once you're logged in, you'll see a page similar to the image below.

Create a Sandbox

Discover how to set up a sandbox on BuildBear for seamless DApp development and testing. Customize your environment, fork from supported blockchains, and access essential tools for debugging and verification.

Create Your BuildBear Sandbox

Click Create a Sandbox to start configuring your test blockchain.

Forking Options

This feature enables you to create a sandbox, forked from the state of any supported blockchain, at any block number, with a randomly generated chain ID.

You can also create a test blockchain without forking from an existing chain.

Advanced Options

When creating a Sandbox, you can configure additional options to customize your environment:

Deploy Large Contracts: Enable contracts larger than the default 24KB limit.
Unlocked Accounts: Access unlocked accounts for easier script execution.
Mnemonic: Generate a unique mnemonic phrase for your testnet.
Override Gas Estimation: Detect and override gas estimation failures.
Impersonation Transactions: Allow transactions to be sent from any address for testing purposes.
Snapshots: Take snapshots of the blockchain state for easy rollbacks.
Block Mining & Timestamp Manipulation: Manually mine blocks and adjust timestamps.

Configure these options based on your development needs to optimize testing and debugging.

Your RPC Is Ready for Use

After clicking Create, select Go to Dashboard to access your newly created sandbox.

On the Dashboard, you’ll find essential details and tools to manage your test environment efficiently.

Each sandbox ships with a funded mnemonic. To extract the first account’s key:

cast wallet address PRIVATE_KEY

Use the wallet address to obtain funds from your sandbox faucet.

Faucet

The BuildBear Faucet provides an easy way to acquire native and ERC-20 tokens for your testnet sandbox. Whether you’re testing transactions or deploying smart contracts, you'll need tokens for gas fees. Use the faucet to mint both native tokens and ERC-20 tokens to fund your development efforts.

Start by selecting the type of token you need (native or ERC-20), and you’ll receive the required tokens instantly. The faucet ensures a seamless experience for developers testing on BuildBear’s platform.

Get ERC20 Tokens

The BuildBear Faucet allows you to request testnet tokens for your blockchain projects, enabling smooth testing and development.

Add ERC-20 Tokens

Click Faucet in the left navigation pane.

Use the faucet to mint ERC-20 tokens for your testing needs.

The faucet provides a list of supported ERC-20 tokens. You can select the token you wish to mint from the list.

Get Native Tokens

The BuildBear Faucet allows you to request testnet tokens for your blockchain projects, enabling smooth testing and development.

Add Native Tokens or ERC-20 Tokens

Click Faucet in the left Navigation Pane.

To perform transactions on any sandbox, you’ll need native tokens for gas fees. Use the faucet to acquire them.

Plugins Installation

Install the required plugins from the BuildBear Plugin Marketplace.

Contracts Verification API

Verify your smart contracts and fetch verified contract artifacts via BuildBear’s unified verification endpoints.

Supported Verification Types

Foundry

Etherscan
Sourcify

Hardhat

Etherscan
Sourcify

Refer to the following doc to learn to Verify Contracts on BuildBear Sandboxes.

Docs - Contracts Verification API - BuildBear Labs

BuildBear Explorer

BuildBear Explorer provides an intuitive and powerful interface for monitoring blockchain transactions. Whether you’re debugging smart contracts or tracking transaction history, the explorer offers real-time insights and seamless navigation.

Key Features

Transaction Monitoring – View pending and confirmed transactions across multiple explorers (BuildBear, BlockScout, and Ethernal).
Detailed Transaction Insights – Access transaction details, including hash, block number, sender/receiver addresses, and gas usage.
Advanced Debugging Tools – Utilize Sentio Tracer, Sentio Debugger, and Simbolik Debugger for in-depth contract execution analysis.
External Explorer Support – Open transactions in third-party explorers directly from BuildBear.

Monitoring Transactions on BuildBear Explorer

Click Explorer in the left Navigation Pane.

A list of transactions will be displayed. You can filter the transactions by All, Pending, and Confirmed.

You can also expand the Explorer menu to select a default explorer from BuildBear, BlockScout, or Ethernal.

Click on a transaction to view its details. The transaction details page includes information such as the transaction hash, block number, sender and receiver addresses, etc.

Transaction Debugging

The Transaction Details page provides essential debugging tools, including Sentio Tracer, Sentio Debugger, and Simbolik Debugger, to analyze transaction execution.

At the top, next to View all Transactions, you’ll find a drop-down menu to open the current transaction’s details in an external explorer of your choice.

Building a Cross-Chain Bridge with Node Relayer on BuildBear

We will build a minimal, event-driven bridge that works end-to-end across two BuildBear Mainnet Sandboxes (Ethereum and Polygon).
Instead of mocks, we will attach real Chainlink ETH/USD feeds via the BuildBear Data Feeds plugin, verify contracts with Sourcify, and debug transactions with Sentio, all in BuildBear's Sandboxes.

What We Will Learn

Setting up two BuildBear Mainnet Sandboxes (ETH and Polygon)
Installing the Data Feeds plugin and attaching the WETH/USD feed on both Sandboxes
Preparing environment variables and Foundry configs
Deploying the Bridge with Foundry and verifying via Sourcify
Running a bi-directional relayer to detect and release assets on the destination chain
Interacting with the bridge (WETH ⇄ USDT) and inspecting results
End-to-End transaction debugging with Sentio and BuildBear explorer

Project Repository

You can either use the repository provided by us or create your own Foundry Project. Here, we will use the repository that we have provided.

GitHub - BuildBearLabs/tutorial-buildbear-datafeed-bridge: Build a minimal event-driven bridge (WETH ⇄ USDT) using Foundry and Node relayer, fully built in BuildBear Mainnet Sandboxes with the Chainlink DataFeed Plugin.

How it Works

The following snapshots provide a quick, visual understanding of the system before diving into the code. Add your rendered-mermaid images where indicated.

High-level sequence
1. The user approves and calls lockAndQuote on the source bridge.
2. The bridge pulls the source token, reads WETH/USD from the data feed, computes the destination amount, and emits BridgeRequested.
3. The relayer observes that event on the source chain and calls release on the destination bridge with the mapped token, amount, and nonce.
4. The destination bridge checks the nonce, transfers tokens to the recipient, and emits TransferReleased.
5. The destination side is pre-funded, and the relayer must be running for events to be processed.
Contract internals
1. Lock-and-Quote Functionality
  1. Take custody of the source token via safeTransferFrom.
  2. Read WETH/USD from the data feed and normalize for math.
  3. Handle decimals and calculate the destination amount.
  4. Emit BridgeRequested.
  5. Increment nonce.
2. Release Functionality
  1. Enforce admin-only access.
  2. Ensure the external nonce is unused and mark it processed.
  3. Transfer tokens out to the recipient.
  4. Emit TransferReleased.

Directory and Project Structure

Create Sandboxes and Install Plugins

Create two Mainnet Sandboxes:

Ethereum Mainnet
Polygon Mainnet

💡

Use the code DD-BB-BLOG to receive 1 month of free BuildBear Premium. Activate your premium access from here and start enjoying the benefits immediately.

Install the following plugins on both Ethereum and Polygon Mainnet Sandboxes:

Installing and configuring the Chainlink Data Feed Plugin.
- Install the "Chainlink Data Feed" Plugin from the Plugin Marketplace.
- Search and Subscribe to the "ETH/USD" feed.
- Once you have installed the Data-Feeds on both the Sandboxes, verify that your feed addresses match the addresses below:
  - Ethereum Mainnet (ETH/USD Feed): 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
  - Polygon Mainnet (ETH/USD Feed): 0xF9680D99D6C9589e2a93a78A04A279e509205945

You can also visit Chainlink Data Feed Dashboard to see your subscribed feeds, and add/remove feeds.

Also, install Sentio, Simbolik & Sourcify Plugins from BuildBear Plugin Marketplace.

Simbolik relies on Sourcify-verified source code to debug contracts. It currently works best for unoptimized contracts as there can be limited debugging information and inconsistencies, with optimized builds. Support for optimized contracts is improving with Solidity’s debugging tooling.

Before running any transactions:

Go to your Sandbox's Plugins tab
Look for Sourcify, Simbolik, and Sentio plugins**.**
Click Install Plugin

Environment Variables & Wallet Setup

Create a basic Foundry Project, and copy .env.example to .env and fill in values or use the env example below. We have some values pre-filled to save you some time sleuthing for addresses. These mirror Mainnet token addresses and price feed addresses that BuildBear exposes inside the Sandboxes after the plugins are installed and configured.

# RPC endpoints (your BuildBear Sandbox RPC URLs) 
ETH_MAINNET_SANDBOX=<YOUR_ETH_MAINNET_SANDBOX_URL> 
POL_MAINNET_SANDBOX=<YOUR_POLYGON_MAINNET_SANDBOX_URL> 

# Deployer/admin key & address 
PRIVATE_KEY= WALLET_ADDRESS= 

# Chainlink WETH/USD feeds (mainnet addresses) 
MAINNET_FEED_WETH_USD=0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
POLYGON_FEED_WETH_USD=0xF9680D99D6C9589e2a93a78A04A279e509205945 

# Token addresses (mainnet addresses; mirrored in BuildBear Sandboxes) 
ETH_WETH_TOKEN=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 
ETH_USDT_TOKEN=0xdAC17F958D2ee523a2206206994597C13D831ec7 
POL_WETH_TOKEN=0x7ceb23fd6bc0add59e62ac25578270cff1b9f619 
POL_USDT_TOKEN=0xc2132D05D31c914a87C6611C10748AEb04B58e8F 

# EOA used to perform lockAndQuote 
RECEIVER_WALLET= 
RECEIVER_PRIVATE_KEY=

`foundry.toml`

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
# required to dynamically read and interact with latest bridge addresses
fs_permissions = [{ access = "read", path = "./broadcast/DeployBridge.s.sol/" }]
remappings = ['@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts']
[rpc_endpoints]
eth_mainnet_sandbox = "${ETH_MAINNET_SANDBOX}"
pol_mainnet_sandbox = "${POL_MAINNET_SANDBOX}"

We also need some npm packages for the relayer to work, refer to the package.json file or put the contents below in it:

{
  "scripts": {
    "start": "npm run start-relayer",
    "start-relayer": "tsx ./relayer/index.ts"
  },
  "dependencies": {
    "dotenv": "^16.3.1",
    "ethers": "^6.13.5",
    "permissionless": "^0.2.47",
    "viem": "^2.30.0"
  },
  "devDependencies": {
    "@types/node": "^20.11.10",
    "tsx": "^3.13.0"
  }
}

Need a new wallet keypair? Create one with cast

cast wallet new

Funding your Deployer & Receiver Wallet

Once you have configured your wallets, you will need to fund your wallets with enough funds to:

Cover deployment and interaction gas costs.
Fund the bridges while deployment from deployer to the Bridge
- Requires deployer to hold more than 1000 WETH and 25000 USDT.
Fund the receiver's wallet with some WETH to allow interaction with Bridge.sol and bridge the assets.

Why do we need to pre-fund wallet-addresses?

The relayer's call to release funds depends on the destination bridge already holding the mapped token. Without initial liquidity, release would fail due to insufficient balance.

Creating Contracts & Scripts

`Bridge.sol` Contract

Roles and Storage

admin: deployer; the only permitted caller to release.
nonce: increments per request; included in BridgeRequested.
processedNonces: marks opposite-chain nonces as used to prevent re-release.
wethToken, usdtToken: ERC-20s handled on this chain.
wethUsdFeed: Chainlink WETH/USD aggregator.

Price & Quotes

_getWethPrice() reads Chainlink and normalizes the result to 1e8 decimals for stable math.
Pulls srcAmount in via safeTransferFrom.
Gets WETH/USD price once & computes dstAmount
Emits BridgeRequested(...) and increments nonce.

Assets Release Post-Bridging

Triggered by the relayer with onlyAdmin restriction and check for unused processedNonces[externalChainNonce], and marks it used.
Transfers amount of token to to.
Emits TransferReleased(...).

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

interface AggregatorV3Interface {
    function decimals() external view returns (uint8);
    function latestRoundData() external view returns (uint80, int256, uint256, uint256, uint80);
}

contract Bridge {
    using SafeERC20 for IERC20;

    address public admin;
    uint256 public nonce;
    mapping(uint256 => bool) public processedNonces;

    address public wethToken;
    address public usdtToken;
    address public wethUsdFeed;

    event BridgeRequested( // still present, but will be filled by relayer mapping
        address indexed from,
        address indexed to,
        address srcToken,
        address dstToken,
        uint256 srcAmount,
        uint256 dstAmount,
        uint256 nonce,
        uint256 date
    );

    event TransferReleased(address indexed to, address token, uint256 amount, uint256 externalChainNonce, uint256 date);

    modifier onlyAdmin() {
        require(msg.sender == admin, "Not admin");
        _;
    }

    constructor(address _weth, address _usdt, address _wethUsdFeed) {
        admin = msg.sender;
        wethToken = _weth;
        usdtToken = _usdt;
        wethUsdFeed = _wethUsdFeed;
    }

    function _getWethPrice() internal view returns (uint256) {
        AggregatorV3Interface feed = AggregatorV3Interface(wethUsdFeed);
        (, int256 answer,,,) = feed.latestRoundData();
        require(answer > 0, "invalid answer");

        uint8 dec = feed.decimals();
        uint256 price = uint256(answer);

        if (dec > 8) price = price / (10 ** (dec - 8));
        else if (dec < 8) price = price * (10 ** (8 - dec));

        return price; // 1e8
    }

    function lockAndQuote(address srcFromToken, address srcToToken, uint256 srcAmount, address to) external {
        IERC20(srcFromToken).safeTransferFrom(msg.sender, address(this), srcAmount);

        uint256 dstAmount;

        uint256 wethPrice = _getWethPrice(); // 1e8

        if (srcFromToken == wethToken && srcToToken == usdtToken) {
            // WETH → USDT
            dstAmount = (srcAmount * wethPrice) / 1e8 / 1e12; // adjust 18→6 decimals
        } else if (srcFromToken == usdtToken && srcToToken == wethToken) {
            // USDT → WETH
            dstAmount = (srcAmount * 1e12 * 1e8) / wethPrice; // adjust 6→18 decimals
        } else {
            revert("unsupported token pair");
        }

        emit BridgeRequested(msg.sender, to, srcFromToken, srcToToken, srcAmount, dstAmount, nonce, block.timestamp);
        nonce++;
    }

    function release(address token, address to, uint256 amount, uint256 externalChainNonce) external onlyAdmin {
        require(!processedNonces[externalChainNonce], "already processed");
        processedNonces[externalChainNonce] = true;

        IERC20(token).safeTransfer(to, amount);

        emit TransferReleased(to, token, amount, externalChainNonce, block.timestamp);
    }
}

interface IERC20Metadata is IERC20 {
    function decimals() external returns (uint8 decimals);
}

Foundry Scripts & Their Usage

`HelperConfig.s.sol`

Defines a NetworkConfig struct that carries:
- deployerKey (private key pulled from env),
- wethToken, usdtToken,
- wethUsdFeed,
- deployer (EOA that will pre-fund the bridge).
Chooses activeNetworkConfig based on block.chainid:
- 1 for the Ethereum Sandbox,
- 137 for the Polygon Sandbox.
All addresses and keys are read, vm.env* so you configure once in .env.

When to reference it:

Deployment and interaction scripts are used HelperConfig to get chain-specific parameters without branching logic scattered across scripts.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Script} from "forge-std/Script.sol";

contract HelperConfig is Script {
    struct NetworkConfig {
        uint256 deployerKey;
        address wethToken;
        address usdtToken;
        address wethUsdFeed;
        address deployer;
    }

    NetworkConfig public activeNetworkConfig;

    constructor() {
        if (block.chainid == 1) {
            activeNetworkConfig = getEthMainnetConfig();
        } else if (block.chainid == 137) {
            activeNetworkConfig = getPolygonMainnetConfig();
        } else {
            revert("Unsupported network");
        }
    }

    function getEthMainnetConfig() public view returns (NetworkConfig memory) {
        return NetworkConfig({
            deployerKey: vm.envUint("PRIVATE_KEY"),
            wethToken: vm.envAddress("ETH_WETH_TOKEN"), // BuildBear faucet weth token
            usdtToken: vm.envAddress("ETH_USDT_TOKEN"), // BuildBear faucet USDT token
            wethUsdFeed: vm.envAddress("MAINNET_FEED_WETH_USD"),
            deployer: vm.envAddress("WALLET_ADDRESS")
        });
    }

    function getPolygonMainnetConfig() public view returns (NetworkConfig memory) {
        return NetworkConfig({
            deployerKey: vm.envUint("PRIVATE_KEY"),
            wethToken: vm.envAddress("POL_WETH_TOKEN"), // BuildBear faucet weth token
            usdtToken: vm.envAddress("POL_USDT_TOKEN"), // BuildBear faucet USDT token
            wethUsdFeed: vm.envAddress("POLYGON_FEED_WETH_USD"),
            deployer: vm.envAddress("WALLET_ADDRESS")
        });
    }
}

`DeployBridge.s.sol`

Starts a broadcast with deployerKey.
Deploys Bridge(wethToken, usdtToken, wethUsdFeed). The deployer becomes admin.
Pre-funding from deployer to the deployed bridge:
- Requires deployer to hold more than 1000e18 WETH and 25_000e6 USDT.
- Transfers a fixed seed amount to the bridge (1000e18 WETH and 25_000e6 USDT).
  - Lower or remove the require thresholds to demo with smaller balances.
  - Add more tokens or feeds by extending constructor arguments and storage.

Why the pre-funding check exists?

The relayer's call to release funds depends on the destination bridge already holding the mapped token. Without initial liquidity, release would fail due to insufficient balance.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Script} from "forge-std/Script.sol";
import {console2} from "forge-std/console2.sol";

import {HelperConfig} from "script/HelperConfig.s.sol";
import {Bridge, IERC20, SafeERC20} from "src/Bridge.sol";

contract DeployBridge is Script {
    using SafeERC20 for IERC20;

    function run() external {
        (uint256 deployerKey, address wethToken, address usdtToken, address wethUsdFeed, address deployer) =
            new HelperConfig().activeNetworkConfig();

        vm.startBroadcast(deployerKey);

        // Deploy bridge
        Bridge bridge = new Bridge(wethToken, usdtToken, wethUsdFeed);

        // Optionally pre-fund bridge with WETH + USDT liquidity from deployer
        uint256 wethBal = IERC20(wethToken).balanceOf(deployer);
        uint256 usdtBal = IERC20(usdtToken).balanceOf(deployer);
        require(wethBal > 1000e18, "Fund your account with atleast 1000 WETH tokens");
        require(usdtBal > 25000e6, "Fund your account with atleast 25000 USDT tokens");

        if (wethBal > 0) {
            // IERC20(wethToken).approve(address(bridge), 1000e18);
            IERC20(wethToken).safeTransfer(address(bridge), 1000e18);
        }
        if (usdtBal > 0) {
            // IERC20(usdtToken).approve(address(bridge), 25000e6);
            IERC20(usdtToken).safeTransfer(address(bridge), 25000e6);
        }

        vm.stopBroadcast();

        console2.log("Bridge deployed at:", address(bridge));
        console2.log("WETH/USD feed:", wethUsdFeed);
    }
}

`InteractBridge.s.sol`

Reads the deployed bridge address for the current block.chainid from broadcast/DeployBridge.s.sol/<chainId>/run-latest.json.
Loads wethToken and usdtToken from HelperConfig.
Uses RECEIVER_WALLET and RECEIVER_PRIVATE_KEY to send the tx.
Approves the source token, then calls lockAndQuote(wethToken, usdtToken, 1e18, receiver) to perform WETH → USDT on the current chain.
Emits BridgeRequested, which the relayer observes to call release on the opposite chain.
For USDT → WETH, swap the token params from before and use, 6-decimals (e.g., 1000e6).
Works on chain 1 and 137 since addresses come from HelperConfig and broadcast files at runtime.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Script} from "forge-std/Script.sol";
import {console2} from "forge-std/console2.sol";
import {Bridge, IERC20, SafeERC20} from "src/Bridge.sol";
import {HelperConfig} from "script/HelperConfig.s.sol";

contract InteractBridge is Script {
    using SafeERC20 for IERC20;

    function run() external {
        // Load JSON from broadcast folder (network-specific)
        string memory path = string.concat(
            vm.projectRoot(), "/broadcast/DeployBridge.s.sol/", vm.toString(block.chainid), "/run-latest.json"
        );
        string memory json = vm.readFile(path);

        // Parse contract address from broadcast
        address bridgeAddr = abi.decode(vm.parseJson(json, ".transactions[0].contractAddress"), (address));
        console2.log("Bridge found at:", bridgeAddr);

        Bridge bridge = Bridge(bridgeAddr);

        // Load network config
        (, address wethToken, address usdtToken,,) = new HelperConfig().activeNetworkConfig();

        // Wallet for interaction
        address receiver = vm.envAddress("RECEIVER_WALLET");
        uint256 receiverKey = vm.envUint("RECEIVER_PRIVATE_KEY");
        console2.log("EOA Interacting with Bridge:", receiver);

        // Interact: approve WETH and call lockAndQuote
        vm.startBroadcast(receiverKey);

        uint256 amount = 1e18; // 1 WETH
        IERC20(wethToken).approve(bridgeAddr, amount);

        bridge.lockAndQuote(wethToken, usdtToken, amount, receiver);

        vm.stopBroadcast();

        console2.log("lockAndQuote called with", amount, "WETH -> expecting USDT");
    }
}

How do these scripts work together?

Deploy the bridge on both Sandboxes. Each bridge has its own admin and token/feed wiring.
Pre-fund both bridges with the destination tokens you expect to release.
Start the relayer. It subscribes to BridgeRequested on both chains, maps tokens for the opposite chain, and calls release as the admin there.
Run the interaction script on the source chain. It locks tokens and emits the event. The relayer fulfills on the destination chain.

This separation keeps on-chain logic minimal and pushes cross-chain coordination into the relayer, which is appropriate for an educational, event-driven demo.

Relayer

Purpose: watch BridgeRequested on the source chain and call release on the destination chain as the bridge admin.
Setup: loads bridge addresses from Foundry broadcasts, creates JSON-RPC providers, and builds a signer on the destination chain using PRIVATE_KEY.
Flow: poll logs for BridgeRequested, parse {to, dstToken, dstAmount, nonce}, map dstToken via TOKEN_MAP, then send release(mappedDstToken, to, dstAmount, nonce) on the destination bridge.
Safety: destination bridge enforces one-time processing with processedNonces[nonce] to prevent replay.
Requirements: destination bridge must hold sufficient token liquidity; the signer must be the bridge admin.
Scope: the shown script is one-directional (ETH to POL). To support both directions, add a second poller for Polygon and call release on Ethereum with an ETH-side admin signer.
Limitation: processes only events observed while running; no backfill of past events.

import fs from "fs";
import path from "path";
import { ethers } from "ethers";
import BridgeAbi from "../out/Bridge.sol/Bridge.json";
import "dotenv/config";

function getLatestDeployment(chainId: number) {
  const filePath = path.join(
    __dirname,
    `../broadcast/DeployBridge.s.sol/${chainId}/run-latest.json`
  );
  const raw = fs.readFileSync(filePath, "utf-8");
  const json = JSON.parse(raw);
  const tx = json.transactions.find((t: any) => t.transactionType === "CREATE");
  if (!tx) throw new Error("No CREATE transaction in broadcast file");
  return tx.contractAddress;
}

const ETH_RPC = process.env.ETH_MAINNET_SANDBOX!;
const POL_RPC = process.env.POL_MAINNET_SANDBOX!;
const PK = process.env.PRIVATE_KEY!;

// cross-chain token mapping
const TOKEN_MAP: Record<string, string> = {
  [process.env.ETH_USDT_TOKEN!]: process.env.POL_USDT_TOKEN!,
  [process.env.ETH_WETH_TOKEN!]: process.env.POL_WETH_TOKEN!,
  [process.env.POL_USDT_TOKEN!]: process.env.ETH_USDT_TOKEN!,
  [process.env.POL_WETH_TOKEN!]: process.env.ETH_WETH_TOKEN!,
};

async function main() {
  const ethProvider = new ethers.JsonRpcProvider(ETH_RPC);
  const polProvider = new ethers.JsonRpcProvider(POL_RPC);
  const wallet = new ethers.Wallet(PK, polProvider);

  const ethBridgeAddr = getLatestDeployment(1);
  const polBridgeAddr = getLatestDeployment(137);

  console.log("ETH Bridge:", ethBridgeAddr);
  console.log("POL Bridge:", polBridgeAddr);

  const ethBridge = new ethers.Contract(
    ethBridgeAddr,
    BridgeAbi.abi,
    ethProvider
  );
  const polBridge = new ethers.Contract(polBridgeAddr, BridgeAbi.abi, wallet);

  const bridgeRequestedTopic = ethers.id(
    "BridgeRequested(address,address,address,address,uint256,uint256,uint256,uint256)"
  );

  let lastProcessed = await ethProvider.getBlockNumber();
  console.log("Relayer started. Watching new events...");

  setInterval(async () => {
    try {
      const latestBlock = await ethProvider.getBlockNumber();
      if (latestBlock <= lastProcessed) return;

      const logs = await ethProvider.getLogs({
        fromBlock: lastProcessed + 1,
        toBlock: latestBlock,
        address: ethBridgeAddr,
        topics: [bridgeRequestedTopic],
      });

      for (const log of logs) {
        const parsed = ethBridge.interface.parseLog(log);
        let { from, to, srcToken, dstToken, srcAmount, dstAmount, nonce } =
          parsed.args;

        console.log("Detected BridgeRequested:");
        console.log({
          from,
          to,
          srcToken,
          dstToken,
          srcAmount,
          dstAmount,
          nonce,
        });

        // map token for destination chain
        const mappedDstToken = TOKEN_MAP[dstToken] || dstToken;

        try {
          const tx = await polBridge.release(
            mappedDstToken,
            to,
            dstAmount,
            nonce
          );
          console.log("Release tx sent:", tx.hash);
          await tx.wait();
          console.log("Release confirmed.");
        } catch (err) {
          console.error("Release failed:", err);
        }
      }

      lastProcessed = latestBlock;
    } catch (err) {
      console.error("Polling error:", err);
    }
  }, 10_000);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});

Configuring Makefile

Now with the project set up, we can configure commands in a Makefile to deploy, verify and interact with bridges on different sandboxes.

Put this Makefile at the project root. It installs dependencies, deploys with Sourcify verification on both Sandboxes, and provides interaction targets. It basically takes away the overhead of writing commands again and again, working with complex commands and replacing them with simpler ones.

Remember to replace the placeholders in verifier-urls below with your actual BuildBear Sandbox ID

.PHONY: make-deploy install deploy-mainnet-sourcify deploy-pol-sourcify interact-mainnet-bridge interact-pol-bridge

install:
    forge install && npm i && forge build


deploy-mainnet-sourcify:
    forge script script/DeployBridge.s.sol \
     --rpc-url eth_mainnet_sandbox \
     --verifier sourcify \
     --verify \
     --verifier-url https://rpc.buildbear.io/verify/sourcify/server/<eth-mainnet-Sandbox-id> \
     --broadcast \


deploy-pol-sourcify:
    forge script script/DeployBridge.s.sol \
     --rpc-url pol_mainnet_sandbox \
     --verifier sourcify \
     --verify \
     --verifier-url https://rpc.buildbear.io/verify/sourcify/server/<polygon-mainnet-Sandbox-id>  \
     --broadcast \


interact-mainnet-bridge:
    forge script script/InteractBridge.s.sol \
     --rpc-url eth_mainnet_sandbox \
     --broadcast \


interact-pol-bridge:
    forge script script/InteractBridge.s.sol \
     --rpc-url eth_mainnet_sandbox \
     --broadcast \

How it is set up:

install installs Foundry dependencies, Node packages, and builds contracts.
deploy-mainnet-sourcify deploys to the ETH Sandbox and verifies via the Sourcify plugin endpoint.
deploy-pol-sourcify deploys to the Polygon Sandbox and verifies via the corresponding Sourcify plugin endpoint.
interact-mainnet-bridge runs your interaction script against the ETH Sandbox to bridge assets.
interact-pol-bridge runs your interaction script against the Polygon Sandbox to bridge assets.

Install and Build

make install

This installs Foundry dependencies into lib, installs Node dependencies for the relayer, and compiles the contracts.

Deploy and Verify

Deploy both bridges:

make deploy-mainnet-sourcify deploy-pol-sourcify

Your Foundry broadcast files will include the deployed addresses. Sourcify verification will be available in the Sandbox explorer.

Pre-funding note from your deploy script:

Ensure the deployer wallet has sufficient WETH and USDT in both Sandboxes for the seed transfers. Adjust or remove the require checks inside the script if you want smaller demo amounts.

Start the Relayer

Remember to install the dependencies as mentioned before, and run the relayer:

npm start

This relayer processes only those events that occur while it is running. Backfill isn't supported, by the script for the purpose of simplicity and ease of implementation

Interact and Bridge the Assets

ETH to Polygon Bridging:

Remember to start the relayer before you call the Interact-Bridge Script on either of the Sandboxes.

While the relayer is running, in another terminal, execute an interaction with the bridge

# This will emit a bridge request from ETH ---> Polygon for WETH to USDT
make interact-mainnet-bridge

Script Broadcast

Tx on BuildBear Explorer

Your interaction script reads the last deployment address from Foundry broadcasts, approves the source token, and calls lockAndQuote. The relayer observes the BridgeRequested event on the source chain and calls release on the destination bridge.

In the output below, the relayer captured the BridgeRequested(...) event and released the asset on the Polygon Mainnet Sandbox
Asset release tx on Polygon Mainnet Sandbox

Transaction Debugging with the Sentio Plugin

This section is optional and shows how to inspect an end-to-end transfer using the explorer and Sentio. For the Sentio Debugger to work, you will need to install the Sentio Plugin from BuildBear Plugin Marketplace

Source: Bridging Tx

Open the source Sandbox explorer.

Find the tx hash for the interaction with lockAndQuote, on the bridge contract.

Click on View Trace on Sentio.

Fund Flow

A visual map of token movement for the source transaction. Use it to confirm transferFrom into the bridge and any intermediate ERC20 flows.

Call Trace

A step-by-step execution trace. Helpful to see the call into lockAndQuote, the oracle read, and the event emission order.

Call Graph

Graph view of calls across contracts during the source transaction. Useful for understanding the sequence and flow of internal calls.

Events Tab

Structured list of emitted events. Verify BridgeRequested fields such as srcToken, dstToken, dstAmount, and nonce.

State Tab

Storage and variable snapshots at key points. Useful for checking nonce increments and any flags written during the call.

Destination: Release Tx

Open the destination Sandbox Explorer.
Find the relayer release transaction on the bridge contract that transfers assets from the bridge to the receiver.
Click on View Trace on Sentio.

Fund Flow

Shows token movement out of the bridge to the receiver. Use it to confirm the final ERC20 transfer with the expected amount.

Call Trace

Execution path for the release call by the relayer. Check the nonce processing and the order of effects before the transfer.

Call Graph

Graph view of the destination call sequence during release. Helps verify checks, effects, interactions, ordering, and the final token transfer.

Events Tab

Verify TransferReleased with the same external nonce used on the source chain, along with token and amount fields.

State Tab

Inspect processedNonces and any relevant balances after the transfer to ensure idempotence and correct accounting.

That’s it. You now have a minimal, event-driven cross-chain bridge running end-to-end in BuildBear Mainnet Sandboxes. You can extend this demo by adding multi-sig relayers, accounting, fees, slippage controls, and stronger verification models.

You have now set up a minimal, event-driven bridge in BuildBear that uses BuildBear’s Data Feeds Plugin for price quoting, verifies via Sourcify Plugin, and can be traced and debugged in Sentio Plugin, all in BuildBear's Sandbox environment.

Exploring Quantum Biology: A New Frontier in Science with Dr. Clarice D. Aiello

2025-09-15T01:15:17.480Z

In a world where science continuously pushes the boundaries of what we know, quantum biology emerges as a fascinating and profound field of study. In a recent episode of DevNTell, Narb introduced us to a captivating conversation with Dr. Clarice D. Aiello from the Quantum Biology Institute. If you ever wondered about the possible intersections of quantum physics and biology, this episode provides remarkable insights.

Intro to Dr. Aiello’s Background

In the episode Dr. Aiello shared her journey from Brazil, through quantum physics training, to spearheading the Quantum Biology Institute in the United States. This multidisciplinary field probes the extent to which biology might utilize quantum mechanics. It's a thrilling consideration: tiny events at the molecular level could influence broader biological processes. The institute aims to prove or refute whether biology truly operates on quantum principles, potentially revolutionizing our understanding and approach to science and technology.

Quantum Biology: Bridging Disciplines

Quantum biology is not merely theoretical. The field explores how biological systems might harness quantum phenomena like superposition to function. Such ideas aren't entirely new, as they've been suggested since 1978. Despite the intriguing possibilities, quantum biology has yet to hit the mainstream due to challenges in funding and research resources. Traditional evidence has been largely correlative, coming from either test tubes or broad biological observations.

Dr. Aiello emphasized the need for advanced instruments to explore these phenomena at the cellular level. These instruments serve as "glorified microscopes" with quantum capabilities, aiming to provide causal data that could firmly establish quantum biology.

Transformative Implications of Quantum Biology

The applications for the research the institute is doing could be far-reaching. From medical therapies using weak magnetic fields to environmental and technological innovations, the potential impact is vast. Dr. Aiello envisions a future where treatments can be non-invasive and cost-effective, possibly accessed through something as ubiquitous as a smartphone. This approach could reshape medicine, offering solutions for conditions ranging from cancer to reproductive health.

She also pointed to the implications for space exploration. As humanity looks to other planets like Mars, understanding how living organisms interact with magnetic fields becomes crucial. If life on Earth is attuned to our planet's magnetic field, what does that mean for biomagnets' potential roles in other environments?

Collaboration and Innovation: The Future of Quantum Biology

Continuous collaboration among quantum physicists, chemists, and biologists is essential for progressing in this novel field. Despite obstacles like underfunding and skepticism, the Quantum Biology Institute is pioneering in its efforts, supported by a decentralized autonomous organization (DAO). They are set to launch a quantum biology incubator to further develop technology in this area.

Dr. Aiello also highlighted a significant effort to share the institute's research openly online, which could democratize access to their groundbreaking work and inspire further collaboration worldwide.

Closing Thoughts

Quantum biology stands as a beacon of scientific potential, aiming to illuminate unknown facets of how life operates. Dr. Aiello’s work at the Quantum Biology Institute invites us to rethink our understanding of life’s complexity. By probing the fundamental connections between quantum mechanics and biological processes, we may uncover new paradigms that drive future scientific and technological innovations.

Links and Resources

Announcing the D_D DevConnect Giveaway

2025-09-12T17:40:44.749Z

With the latest proposal passing in the DAO snapshot vote, we are locked, loaded and ready to revitalize what made Developer DAO great by helping send 3 active contributors to DevConnect with up to $2000 each. We wanted to bring back that “build web3 with friends” vibe that arguably made D_D one of the best developer communities in the ecosystem. Many people who’ve come through the DAO have gone on to have incredible careers, founded multi-million dollar companies and most important of all, made great human connections along the way. Whether chilling in VC5 or hanging out at a global crypto conference, the vibes have always been immaculate which is why we’re looking to help send 3 of the most active members in the community to DevConnect. Who knows, maybe you’ll hack your way to a new job or start a new company 👀

Important Dates

Giveaway Submission Deadline: October 24th, 2025
Winner Selection: Winners will be announced and contacted the week of Oct 31st, 2025 and distribution of funds will follow
- Note: Winners will need to submit proof they can attend and provide some level of KYC
DevConnect: November 17-22, 2025
D_D IRL event at DevConnect: TBA but be sure to subscribe to our Luma Events page to hear about it first

How to Enter the Giveaway

Simply sign up for the giveaway using the following form:

https://devdao.to/devconnect-2025

After you sign up you’ll see a unique referral link be shown to you which you can share with your friends to get you more points when they sign up for the giveaway. So be sure to reach out to your old D_D buddies to refer them to sign up as well! The more referrals you get, the more points you’ll collect which will be taken in consideration in our scoring system when we pick winners.

How to Participate and Win

While the referral points will help your case, it won’t be enough. To really solidify your odds you need to show that you’re an active member of the community with a curated list of D_D related participation activities (see below) that we’ll take into consideration. There is a scoring system behind all of this with all the activities listed below providing scoring points; however, there are some activities that are worth more points then others (e.g. creating tutorial content). In the same vein you don’t want lose out on points for low hanging fruit activities like following social accounts, subscribing to the newsletter, luma events page, minting DevNTell episodes, etc..

Note: The full points system will be revealed at a later date

The more you participate, the more points you’ll earn and more likely it will be that you’ll get selected (past participation also counts)

Participation Activities

General DAO participation

Making high quality tutorial content to help educate others (this is the embodiment of the DAO and what brought a lot of us together in the first place)
- Doesn’t have to be web3/protocol specific, can span the broad range of tech (AI, infra, system design, etc…)
- Avoid strictly AI generated content; however, that’s not to say you can’t use AI to help refine/fine-tune your original work
- Written (blog, X thread, etc…), Video format (YouTube, X video, etc…), GitHub repos, etc…
- Once you’ve created the content be sure to share it on X and tag the DAO’s X Account so we know about it (and can amplify it)
Being a D_D member (being a holder of CODE tokens and/or the D4R NFT)
Voting for snapshots
Participating in proposals in our forum (writing them or providing useful feedback to others)
Following the DAO’s X Account
Subscribing to the Probably Nothing Newsletter
Subscribing to the DAO’s YouTube Channel

D_D Cloud Participation

Signing up for the D_D Cloud waitlist
Following the Futex Labs account on X

DevNTell Participation

Minting episodes for free on the Pods platform
- To mint an episode, visit the DevNTell profile on Pods, connect your wallet and choose the episode you want to mint. Mints are free except for a small platform fee charged by the Pods platform. Mint your favourite episodes and see where you rank on their native leaderboard!
Subscribing to on our Luma Events page
Being a past (or future) guest on the podcast
Follow the DevNTell account on X
Follow the DevNTell account on Instagram
Follow the DevNTell account on TikTok

Good luck and looking forward to rekindling what made D_D such an amazing community to begin with!

Building on Bitcoin Layers With the Hiro Platform

2024-04-16T22:00:00.000Z

Bitcoin is the highest-valued token on the planet, but building on the Bitcoin network was a hassle in the past; as the first blockchain, its support for smart contract development and apps was very basic. This changed with the rise of Bitcoin layer-2 networks like Stacks, which come with powerful smart contract platforms.

In the previous article, you learned the differences between Solidity and Clarity, the programming language used on Stacks. In this article, you will learn how to build smart contracts with Clarity on Stacks and send contract events to a web server with the Chainhook service. All powered by the Hiro Platform.

If you prefer video, check out our workshop with Hiro on YouTube; it contains the same content.

Prerequisites

A Bitcoin wallet that can interact with the Stacks network.
Stacks testnet tokens to pay for the deployments.
A Hiro account to use the Platform IDE.
Node.js to run a server that can handle webhooks.

Setting Up a Hiro Platform Project

To create a contract, you must create a new project on the Hiro Platform. To do so, open the Platform, click “Create Project,” and select “Blank Project”. The Platform will automatically open the project after creation.

The Hiro Platform is the Stacks equivalent to the Remix IDE for Ethereum. It comes preinstalled with all the CLI tools you need for development on Stacks and uses OpenVSCode Server, which is a familiar IDE to most developers.

Building Smart Contracts on Stacks

We will start with the smart contracts. You’ll build your own token, a swap contract for that token, and then leverage a chainhook to listen for contract deployments.

The “Open in Web Editor” button will create a new contract for you and open it in a browser IDE.

Creating a Fungible Token Trait

To create a token contract, we need a trait. This trait defines the function signatures our contract needs to implement to become a SIP-10 token contract (i.e., the Stacks equivalent of ERC-20 contracts on Ethereum).

A trait in Clarity is like an interface in Solidity. In contrast to Solidity, which uses the NPM package manager to install libraries like OpenZeppelin, which helps with contract creation, you need to copy traits manually from templates. The code for SIP token standards is on GitHub.

To create the trait, you open a new terminal, as seen in Figure 1, and execute the following command:

clarinet contract new sip10

The output should look like this:

Created file contracts/sip10.clar
Created file tests/sip10.test.ts
Updated Clarinet.toml with contract sip10

Figure 1: Open terminal

After the command completes, you will have a new contracts/sip10.clar file. Open it and replace its content with this code:

(define-trait sip-010-trait
  (
    (transfer (uint principal principal (optional (buff 34))) (response bool uint))
    (get-name () (response (string-ascii 32) uint))
    (get-symbol () (response (string-ascii 32) uint))
    (get-decimals () (response uint uint))
    (get-balance (principal) (response uint uint))
    (get-total-supply () (response uint uint))
    (get-token-uri () (response (optional (string-utf8 256)) uint))
  )
)

It’s similar to an interface definition in Solidity, as it defines functions a contract has to implement to be standard-conforming. It also enables static checks to validate your contract before deployment.

Implementing the Token Trait

To implement our trait, we create a new contract by running the following command:

clarinet contract new token

It should output the following:

Created file contracts/token.clar
Created file tests/token.test.ts
Updated Clarinet.toml with contract token

Open the new contracts/token.clar file and replace its content with this code:

(impl-trait .sip10.sip-010-trait)

(define-fungible-token clarity-token)

(define-constant ERR_OWNER_ONLY (err u100))
(define-constant ERR_NOT_TOKEN_OWNER (err u101))

(define-constant CONTRACT_OWNER tx-sender)
(define-constant TOKEN_URI u"https://clarity-lang.org")
(define-constant TOKEN_NAME "Clarity Token")
(define-constant TOKEN_SYMBOL "CT")
(define-constant TOKEN_DECIMALS u6)

Let’s go through it step by step.

First, we tell Clarity that the token contract will implement a trait from the SIP-10 contract, allowing us to run a clarinet check to validate that implementation.

Next, we tell Clarity that this contract will be a fungible token, so we can access built-in functions for checking balances and supply or transferring tokens.

Then, we define several constants for error codes and token properties.

Now, we didn’t implement any functions from the trait, so let’s run the following command:

clarinet check

The output should look like this:

note: using deployments/default.simnet-plan.yaml
error: invalid signature for method 'get-balance' regarding trait's specification <sip-010-trait>
x 1 error detected

It tells us we forgot to implement the get-balance function defined by the sip-010-trait.

The check command is helpful because we usually implement already deployed traits, meaning we can’t look at the file that defines the trait. If we run a check, it will tell us the next function we need to implement, and we can repeat this until we have implemented everything correctly.

So, let’s add the missing functions at the bottom of the contracts/token.clar file by pasting the following code:

(define-read-only (get-name)
    (ok TOKEN_NAME)
)

(define-read-only (get-symbol)
    (ok TOKEN_SYMBOL)
)

(define-read-only (get-decimals)
    (ok TOKEN_DECIMALS)
)

(define-read-only (get-balance (who principal))
    (ok (ft-get-balance clarity-token who))
)

(define-read-only (get-total-supply)
    (ok (ft-get-supply clarity-token))
)

(define-read-only (get-token-uri)
    (ok (some TOKEN_URI))
)

;; #[allow(unchecked_data)]
(define-public (transfer
  (amount uint)
  (sender principal)
  (recipient principal)
  (memo (optional (buff 34)))
)
  (begin
    ;; (asserts! (is-eq tx-sender sender) ERR_NOT_TOKEN_OWNER)
    (try! (ft-transfer? clarity-token amount sender recipient))
    (match memo to-print (print to-print) 0x)
    (ok true)
  )
)

(define-public (mint 
    (amount uint)
    (recipient principal))
    (begin
        (asserts! (is-eq tx-sender CONTRACT_OWNER) ERR_OWNER_ONLY)
        (ft-mint? clarity-token amount recipient )
    )
))

First, we have several read-only functions, similar to Ethereum's view functions. You can see the calls to the fungible token functions ft-get-balance and ft-get-supply we got by telling Clarity this is a fungible token at the top of the file.

We have a transfer function, which usually checks that the sender argument contains the same as the tx-sender, but for this tutorial, we commented this line out. Then, there is a match function, which will put the memo argument into a to-print variable and pass it to print the memo argument if it exists. Calls to print are the equivalent to emit in Ethereum.

Finally, we have a mint function that creates new tokens.

This is a complete SIP-10-compliant token contract. Next, we implement a simple swap for it.

Implementing a Token Swap

For the swap, we create a new contract with the clarinet CLI again:

clarinet contract new swapper

The output looks like this:

Created file contracts/swapper.clar
Created file tests/swapper.test.ts
Updated Clarinet.toml with contract swapper

Then, we add the following code into the new contracts/swapper.clar file:

(use-trait sip10-token .sip10.sip-010-trait)

(define-public (swap 
        (from-token <sip10-token>) 
        (to-token <sip10-token>) 
        (amount uint)
    )
    (begin
        (try! (contract-call? 
            from-token 
            transfer 
            amount  
            tx-sender 
            (as-contract tx-sender) 
            none
        ))

        (try! (contract-call? 
            to-token 
            transfer 
            amount 
            (as-contract tx-sender) 
            tx-sender 
            none
        ))
        (ok true)  
    )
)

This is a naive example of a swap that simply exchanges tokens at a 1:1 rate. It has only one function, which uses our sip-010-trait and expects three arguments: two for the tokens and one for the number of tokens the contract should swap.

To give the creator of a token and the swapper tokens, you must add the following code at the end of contract/token.clar:

(mint u1000000 tx-sender)
(mint u4200000 .swapper)

This will be executed at the deployment of the token contract so that each new token deployed from our contract will give the swapper liquidity instantly.

Deploying the Contracts

To deploy your project, go to the Hiro Platform, open your project, and click the “Deploy Project” button on the top right. You have to connect your wallet and choose “Generate for Testnet”.

Figure 2: Deploy project.

If you don’t have enough testnet STX, click the “Request STX” button. Receiving the testnet STX can take a few minutes.

You should see the three contracts and click the “Deploy” button, which will trigger three signing requests to your wallet, one for each contract. Deploying the contracts can take a few minutes.

Figure 3: Deployment plans

After a successful deployment, you will see three “Deployed” links, as shown in Figure 4.

Figure 4: Deployed contracts

Click on one for the token contract to open it in Hiro’s Stacks Explorer. Keep it open; we need it to copy a few values and call a function later.

Figure 5: Stacks Explorer

Sending Smart Contract Events to a Web Server

Now that you have built a token and a simple exchange, the next step is letting off-chain applications, like web servers, react to events these contracts emit. For example, to notify you that someone deployed a new contract or to index the contract data off-chain. For this, Hiro created Chainhooks, a service that monitors the Bitcoin and Stacks networks for events and sends them to a web server via a webhook.

Creating a Web Server

First, we create a simple web server with Node.js. For this, we create a new Node.js project and add a dependency with the following commands:

mkdir web-hook-server && cd web-hook-server
npm init -y
npm i -D localtunnel

The localtunnel package lets us make the server accessible for the chainhook later.

Create a server.js file with this code:

const PORT = 8080

require("http")
  .createServer((request, response) => {
    let body = ""
    request.on("data", (chunk) => {
      body += chunk
    })

    request.on("end", () => {
      console.log(JSON.parse(body))
      response.end()
    })
  })
  .listen(PORT)

require("localtunnel")({ port: PORT }).then((tunnel) => {
  console.log(tunnel.url)
})

Start the server to get a public URL when creating the chainhook.

node server.js

Copy the URL for later, but remember you get a new public URL each time you restart the server!

Creating a Chainhook in the UI

To create a chainhook, open your project in the Hiro platform, select the “Chainhooks” tab, and click the “Create Hook” button.

Figure 4: Chainhooks tab

This will open a form where you must enter the chainhook’s configuration. In this example, we want to listen to new contract deployments, so the config should look like in Figure 5.

Figure 5: Chainhook configuration

Use the inputs as seen in Figure 5, but make the following changes:

Replace “STX Address” with the “Deployed By” value from the Stacks Explorer.
Replace the “Start Block” with the “Block Height” value from the Stacks Explorer.
Replace the URL with the public URL printed by your web server.

If you don’t set an “End Block”, the chainhook will continue listening to deployment events from your address indefinitely.

Finally, you click the “Create Chainhook” button to deploy the hook. After a few seconds, the Hiro Platform should show the latest activity, as in Figure 6.

Figure 6: Chainhook activity

Your web server’s output should look similar to this:

{
  apply: [
    {
      block_identifier: [Object],
      metadata: [Object],
      parent_block_identifier: [Object],
      timestamp: 171...939,
      transactions: [Array]
    }
  ],
  chainhook: {
    is_streaming_blocks: false,
    predicate: {
      deployer: 'ST3...3K3',
      scope: 'contract_deployment'
    },
    uuid: '44e...7c6'
  },
  rollback: []
}

Creating a Chainhook Config With the CLI

Creating a chainhook configuration with the chainhook CLI in the Hiro Platform IDE is also possible. Run the following command to create a new file:

chainhook predicates new mint-hook.json --stacks

This will generate a mint-hook.json file. To listen to the mint events of our token contract, you need to replace the networks attribute in that file with the following content:

"networks": {
  "testnet": {
    "start_block": 152190,
    "if_this": {
      "scope": "contract_call",
      "contract_identifier": "ST3...3K3.token",
      "method": "mint"
    },
    "then_that": {
      "http_post": {
        "url": "https://example.com/api/endpoint",
        "authorization_header": ""
      }
    }
  }
}

Make sure you replace the contract_identifier, start_block, and url with the values from the Stacks Explorer after deploying your contracts. Use the Contract ID from the Stacks Explorer, not the Transaction ID.

Create the chainhook by uploading the mint-hook.json file in the Hiro Platform by opening your project, selecting the “Chainhooks” tab, and clicking the “Upload Chainhook” button on the top right.

Figure 7: Upload chainhook

You can call the function with the Stacks Explorer. Copy the “Deployed by” address, scroll down to the “Available Functions”, and select the mint function.

Figure 8: Available functions

In the form, enter 100 as the amount and the copied address as the recipient, and click “Call Function” to open your wallet, where you have to confirm the transaction.

After a few minutes, your transaction is finalized on Stacks. Your chainhook will trigger, leading to the following output on your web server:

{
  apply: [
    {
      block_identifier: [Object],
      metadata: [Object],
      parent_block_identifier: [Object],
      timestamp: 1711553905,
      transactions: [Array]
    }
  ],
  chainhook: {
    is_streaming_blocks: true,
    predicate: {
      contract_identifier: 'ST3...3K3.token',
      method: 'mint',
      scope: 'contract_call'
    },
    uuid: '906...43b6'
  },
  rollback: []
}

With this, you finally know how to relay smart contract events to an API of your choice. You can process it in any way you like. Use it to notify users of swaps or mints, index all token transactions for easy browsing, or even deploy new contracts in reaction to events!

Summary

The Bitcoin ecosystem got a huge upgrade with the Stacks network, and Hiro makes it accessible for developers. With the Hiro Platform, it’s a matter of a few clicks to deploy Clarity smart contracts and listen to chain events

Comparing Solidity With Clarity

2024-04-10T08:54:05.022Z

Writing smart contracts for Bitcoin was limited in the past, but with Stacks, this changed. Its Clarity programming language allows you to build Bitcoin smart contacts similar to those on the Ethereum network while being more secure than Solidity at the same time. At first glance, Clarity might seem a bit foreign, but the language has many similarities with Solidity, so don't get discouraged by its syntax.

This article adds to our first Stacks workshop with Hiro, where we compared the two languages.

What is Stacks?

Stacks is a layer-2 blockchain network for Bitcoin that reads data from Bitcoin, settles on Bitcoin, and allows the creation of smart contracts similar to the ones on Ethereum.

Besides being a smart contract platform, Stacks also offers several features and services you might know from the Ethereum ecosystem. For example, Stacking DAO is a liquid staking service similar to Lido, and ALEX is a DEX similar to Uniswap.

What is Clarity?

Stacks smart contracts are written in Clarity, a statically typed language with Lisp syntax that favors functional programming styles, including pure functions and immutable data. Its first release date is 2020, so it’s a rather young language, but it benefits from learning from Solidity’s mistakes.

Clarity focuses on security and predictability. It is not Turing complete, which allows for more precise gas estimations and security checks. Conditional jumps or, in high-level languages, if-statements, loops, and recursion are often the cause of complexity in Turing complete languages. Clarity doesn’t support loops or recursion, so there is no way to run indefinitely, making it non-Turing complete. However, you can still review multiple elements with map, filter, and fold functions.

How Does Clarity Differ from Solidity?

Let's review Clarity and Solidity examples to highlight their differences. If you want a more concise visual comparison, check out this site.

We will touch on the following points:

Syntax differences
Immutable variables
Function access
External function calls
Event emission
Token transfer

Syntax Differences

Clarity’s syntax is inspired by Lisp, meaning you will see many parentheses. Clarity favors kebab-case instead of camelCase; everything is an expression since everything is done with functions. There are no statements like if or for that just define code blocks but don’t “return” a value.

Take this example of a function call in Solidity:

functionName(argument1, argument2, …, argumentN);

Compared to the Clarity version:

(function-name argument1 argument2 … argumentN)

Also, no commas or colons are needed.

Assigning Variables

By default, you can change variables directly in Solidity. In Clarity, you can’t; variables are immutable, and you must set them with a call to a built-in function.

In the following Solidity example, we see the use of an assignment operator to change a contract variable.

contract User {
  uint public userAge = 42;
  function updateAge(unit age) public {
    userAge = age;
  }
}

In Clarity, no operator is involved; instead, you call the define-data-var function for contract variables and override it with a var-set function call.

(define-data-var userAge uint 42)
(define-public (update-age (age uint))
  (begin
    (var-set userAge age)
    (ok age)
  )
)

Working With Variables

These variables are immutable; they get replaced by a new instance. This might not be obvious with primitive values like numbers, so let’s look at a more complex example with composite values.

In Solidity, you can use structs to define composite values. The following example illustrates how to define a struct, create an instance, and mutate it.

contract UserContract {
  struct User {
    string name;
    uint age;
  }

  User public user = User("Ryan", 42);

  function updateUser(string memory name, unit age) public {
    user.name = name;
    user.age = age;
  }
}

The Clarity equivalent to a struct is the immutable tuple. Again, it’s created via a built-in function.

(tuple (name "Ryan") (age 42))

This time, some syntactic sugar allows you to define a tuple similar to object literals in JavaScript.

{name: "Ryan", age: 42}

To get data from a tuple, you use the get function. In the following example, we define variables local to the let block and set them to the content of our tuple stored in the user reference.

(define-constant user {name: "Ryan", age: 42})
(let 
  (
    (userName (get name user))
    (userAge (get age user))
  )
  (print {name: userName, age: userAge})
)

If you want to change a tuple value, you have to replace the whole tuple with a new one. Maps can help here, allowing you to reference a tuple by key. This way, you can use a map and a key as a constant reference to a changing value.

(define-map users uint { name: (string-ascii 50), age: uint })
(define-public 
  (add-or-update-user 
    (userId uint) (userName (string-ascii 50)) (userAge uint)
  )
  (map-set users userId { name: userName, age: userAge })
  (ok true)
)

Defining Function Access

To define a function in Solidity, you use the function keyword, followed by parenthesis with the arguments, a list of modifiers, and finally, the function body.

contract UserManagement {
  uint private age;

  function incrementAge() private {
    age += 1;
  }

  function getAge() public view returns (uint) {
    return age;
  }

  function setAge(uint newAge) public {
    age = newAge;
    incrementAge();
  }
}

In Clarity, there are no modifiers but different built-in functions for function definition. Built-in functions define private, public, and view functions called read-only in Clarity. Also, Clarity doesn’t have external functions.

(define-data-var userAge uint u0)

(define-private (increment-age)
  (var-set userAge (+ (var-get userAge) u1))
)

(define-read-only (get-user-age)
  (var-get userAge)
)

(define-public (set-user-age (newAge uint))
  (var-set userAge newAge)
  (ok newAge)
)

Solidity also allows for the definition of custom modifiers to enable you to manage access control.

contract Owned {
  address public owner;

  constructor() {
    owner = msg.sender;
  }

  modifier onlyOwner() {
    require(msg.sender == owner, "Not the owner");
    _;
  }

  function changeOwner(address newOwner) public onlyOwner {
    owner = newOwner;
  }
}

In Clarity, you would use the built-in asserts! function, which will revert your contract automatically if an assertion fails.

(define-data-var owner principal tx-sender)

(define-public (change-owner (newOwner principal))
  (begin
    (asserts! (is-eq tx-sender (var-get owner)) (err u1))
    (var-set owner newOwner)
    (ok true)
  )
)

Calling Functions of Other Contracts

To call a function of another contract in Solidity, you need the address of the contract you want to call and its definition or ABI.

contract User {
  uint public age;

  function setAge(uint newAge) public {
    age = newAge;
  }
}


contract Caller {
  function callSetAge(address userAddress, uint newAge) public {
    UserManagement user = User(userAddress);
    userManagement.setAge(newAge);
  }
}

In Clarity, you need the address (called principal) since everything is handled with built-in functions; classes or contract definitions don’t exist.

(define-data-var age uint u20)

(define-private (increment-age)
  (var-set age (+ (var-get age) u1))
)

(define-public (update-age)
  (increment-age) ;; Internal call
  (ok (var-get age))
)

(define-public (call-set-age (contractA principal) (newAge uint))
  (contract-call? contractA set-age newAge)
)

Emitting Events

In Solidity, similar to structs, you have to define events up-front and explicitly emit them.

contract UserManagement {
  event UserUpdated(string name, uint age);

  function updateUser(string memory name, uint age) public {
    emit UserUpdated(_name, _age);
  }
}

In Clarity, you don’t need to define or emit events explicitly. Built-in functions like stx-transfer emit events implicitly when called. However, if you want a custom event, you can call the print function with a tuple, which will emit an event.

(define-public (update-user (name (string-ascii 32)) (age uint))
  (print { action: "User updated", name: name, age: age })
  (stx-transfer? amount tx-sender recipient)
  (ok true)
)

Transferring Native Tokens

To transfer ETH with Solidity, you’d call the transfer method of a payable address.

contract SendETH {
  function sendViaTransfer(address payable _to) public payable {
    _to.transfer(msg.value);
  }
}

In Clarity, you’d use the built-in stx-transfer function to transfer the native token STX. It checks automatically if the sender has enough tokens.

(define-public (send-stx (recipient principal) (amount uint))
  (stx-transfer? amount tx-sender recipient)
)

Transferring Non-Native Tokens

What would a smart contact-enabled blockchain be without custom tokens? Stacks’ ERC-20 equivalent is the SIP-010 standard.

To transfer a custom (non-native) fungible token in Solidity, you need an interface and call its transfer method with an address and an amount.

interface IERC20 {
  function transfer(address to, uint256 amount) external returns (bool);
}

contract SendERC20 {
  function transferToken(address tokenContract, address to, uint256 _amount) public {
    IERC20 tokenContract = IERC20(_tokenContract);
    tokenContract.transfer(_to, _amount);
  }
}

You can do the same in Clarity by using the built-in contract-call function. No interface is needed since Clarity is not object-oriented and doesn’t support inheritance.

(define-public (transfer-token (recipient principal) (amount uint))
  (contract-call? .token transfer amount tx-sender recipient)
)

Transferring non-fungible tokens in Solidity is similar to the fungible version; you just need an ID instead of an amount.

interface IERC721 {
  function transferFrom(address from, address to, uint256 _tokenId) external;
}


contract SendERC721 {
  function transferNFT(address nftContract, address to, uint256 _tokenId) public {
    IERC721 nftContract = IERC721(_nftContract);
    nftContract.transferFrom(msg.sender, to, tokenId);
  }
}

The same goes for Clarity, again a built-in function with no interface. Also, SIP-009 is Stacks’ equivalent of ERC-721 on Ethereum.

(define-public (transfer-nft (nft-contract principal) (token-id uint) (recipient principal))
  (contract-call? nft-contract transfer token-id tx-sender recipient)
)

Missing Features of Clarity

While this might not be an issue in practice, some missing features make 1:1 ports of smart contracts from Solidity to Clarity a bit harder.

First, Clarity contracts can’t directly modify the state of other contracts, which means building contract factories isn’t possible.

Second, Clarity does not have libraries. In Solidity, you can import an ERC-20 library like OpenZeppelin and extend the interfaces. In Clarity, you would copy and modify code from a SIP-009 template.

Hiro Development Tools for Stacks

Hiro supplies you with all the tools you need to build smart contracts on Stacks.

Clarinet, a development environment similar to Hardhat, for building and testing Clarity contracts.
Stacks.js, a frontend library similar to web3.js, is used to access Stacks from a web application.
The Hiro Platform, a cloud IDE similar to Remix, deploys and debugs Clarity smart contracts.
Chainhook, an indexing service similar to the Graph, to get onchain data quickly.

Summary

Clarity certainly is a unique language for smart contract development. It focuses on the functional programming paradigm and even ditches Turing completeness to make gas estimations and security checks straightforward.

While Clarity might seem quite different at first glance, it still has many conceptual similarities with Solidity, so porting most contracts shouldn’t be a big deal.

Finally, with the tools and services provided by Hiro, you should have your first contract deployed in no time! So, sign up to their platform and tap into the power of Bitcoin!

Ask Hiro on Discord if you have questions about Stacks or Hiro services.

Creating a Token-Gated Web Page With Clarity

2024-03-27T18:43:03.458Z

This tutorial shows how to create a token-gated website using Clarity as the smart contract language. A token-gated website serves content to users with a certain amount of tokens in their wallets.

In this tutorial, we will create two Clarity smart contracts, FanToken and TokenGatedCommunity. Holders of the FanToken can join a community on-chain in the TokenGatedCommunity contract, and our frontend will serve users different content based on membership in the TokenGatedCommunity.

The diagram below illustrates the functionalities of the smart contracts we will be creating.

We will get up and running quickly on the front end by creating a NextJS application using a Stack.js template.

Prerequisites

The author assumes the following prerequisites:

A beginner understanding of Clarity smart contract language
The reader is familiar with the use of a CLI and can navigate between folders via the CLI
Node is installed on the development machine of the reader
Familiarity with React and NextJS

Installing the Clarinet CLI

Clarinet provides a CLI package with a clarity runtime, a REPL, and a testing harness. Clarinet includes a Javascript library, a testing environment, and a browser-based Sandbox. With Clarinet, you can rigorously iterate on your smart contracts locally before moving into production. Install Clarinet here.

Installing the Leather wallet

In this tutorial, we will deploy the smart contracts we write to the testnet environment. To do so, we need to create a wallet and acquire some testnet STX. If you haven't already done so, visit Hiro's wallet page to install the Leather wallet.

After creating a new wallet, make sure to save your seed phrase somewhere safe. You will need it, along with the password you set when creating the wallet, every time you want to log into your wallet after logging out.

You can request some testnet STX by navigating to Hiro's testnet explorer sandbox.

Setting up the project

Now that we have created a wallet let's proceed with the project. Create a new directory on your development machine to house the project. This directory will contain the smart contract and frontend application.

mkdir tokenGateTutorial

cd tokenGateTutorial

The Clarity smart contract will be set up inside the project folder tokenGateTutorial. The clarinet command is used to scaffold a new Clarity project. This command becomes available after the successful installation of Clarity on our development machine.

To scaffold a new Clarity project, run the command below from the location of the tokenGateTutorial folder

clarinet new token-contracts

This command scaffolds a new Clarity smart contract project inside a folder called token-contracts. The folder name can be called anything you wish. Navigate into the token-contracts folder to inspect the files and folders created by the clarinet new folder-name command.

There is acontracts folder where the FanToken and TokenGatedCommunity contracts will be stored. There is also a settings folder that contains three files: Devnet.toml, Mainnet.toml and Testnet.toml. These files contain the seed phrases of wallet accounts used for the deployment of contracts to the different environments of Devnet, Mainnet and Testnet respectively. The project also contains the root Clarinet.toml configuration file and our test folder for writing tests.

Let's get to work and write our smart contract in the next section.

Creating the FanToken contract

Navigate into the contracts folder and run the code below to create a new smart contract.

clarinet contracts new FanToken

This command creates our actual Clarity file, FanToken.clar inside the contracts directory. This is the location where we will write the FanToken contract.

Open the file FanToken.clar, delete the comments inside, and copy and replace the code below into the file.

;; traits
(define-trait sip-010-trait
  (
    (transfer (uint principal principal (optional (buff 34))) (response bool uint))
    (get-name () (response (string-ascii 32) uint))
    (get-symbol () (response (string-ascii 32) uint))
    (get-decimals () (response uint uint))
    (get-balance (principal) (response uint uint))
    (get-total-supply () (response uint uint))
    (get-token-uri () (response (optional (string-utf8 256)) uint))
  )
)

In this snippet above, we are defining traits for a token. A trait is a standard or an interface to which an implementing token must conform. Top on the trait list is atransfer function used to transfer tokens between principals. Addresses in Clarity are referred to asprincipal. There are two types of principal:

Standard Principal: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM :

standard principal is backed by a corresponding private key used for the signing of transactions. This principal starts with the letter ST, denoting that it can only be used in the testnet environment, while the mainnet principal begins with the letter SP and can be used in the mainnet environment.
Contract Principal: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.FanToken :

A contract principal is the address of the deployed contract. It is a combination of the standard principal who deployed the contract and the contract name.

Let's continue with the implementation of the token methods. Copy the code below and add it to the file FanToken.clar


;;previous traits definition above

;; token definitions 
;;one million tokens total supply
(define-fungible-token fanToken u1000000000000) 
;; constants
(define-constant contract-owner tx-sender)
(define-constant err-owner-only (err u100))
(define-constant err-not-token-owner (err u101))
(define-constant err-amount-less-than-zero (err u102))

;;#[allow(unchecked_data)]
(define-public (mint (amount uint) (recipient principal))
    (begin
        (asserts! (> amount u0) err-amount-less-than-zero)
        (ft-mint? fanToken amount recipient)
    )
)

;;#[allow(unchecked_data)]
(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
    (begin
        (asserts! (> amount u0) err-amount-less-than-zero)
        (asserts! (is-eq tx-sender sender) err-not-token-owner)
        (try! (ft-transfer? fanToken amount sender recipient))
        (match memo to-print (print to-print) 0x)
        (ok true)
    )
)
;; read only functions
(define-read-only (get-balance (owner principal))
    (ok (ft-get-balance fanToken owner))
)
(define-read-only (get-total-supply)
    (ok (ft-get-supply fanToken))
)
(define-read-only (get-token-uri)
    (ok none)
)
(define-read-only (get-name)
    (ok "FanToken")
)
(define-read-only (get-symbol)
    (ok "FT")
)
(define-read-only (get-decimals)
    (ok u6)
)

At the top of the code, a fungible token FanToken is defined as Clarity has built-in support for fungible and non-fungible tokens (NFTs). The token has a decimal of 6 digits and a total supply of one million. (define-fungible-token fanToken u1000000000000). The u in front of the digits represents an unsigned integer type.

After the token definition, we have some declared constant values. The first is the contract-owner which is equated to tx-sender. tx-sender refers to the principal executing the transaction. In this instance, the contract-owner will be the deployer of the contract. We also define other constants that denote different error messages.

The mint function is a public function that allocates tokens to a receiver. The function takes in two parameters of type unit and principal. Inside the function body, there's abegin block used to combine different statements for execution.

The assert! block checks for the correctness or truthfulness of a statement. The asserts! check is to see if the amount we want to mint exceeds 0. If the asserts! block passes, the token amount is minted to the recipient principal using the built-in mint function provided by Clarity. (ft-mint? fanToken amount recipient)

This token is set up this way for demonstration purpose as any principal can mint the token.


(define-public (mint (amount uint) (recipient principal))
    (begin
        (asserts! (> amount u0) err-amount-less-than-zero)
        (ft-mint? fanToken amount recipient)
    )
)

Thetransfer function is used to move tokens between different accounts. The transfer function takes four arguments, which are the amount to transfer, the sender (owner) of the token, the recipient of the token, and an optional bytes variable called memo.

Inside the function body, we have abegin block that contains other statements written inside it. The firstasserts! statement checks if the amount being transferred is greater than 0, and the next asserts! statement checks if tx-sender is equal to the sender arguments.

If both asserts! pass, we attempt to transfer the token using another built-in Clarity method,ft-transfer. The transfer of the token is wrapped in a try block. The try block controls the flow of the program; if the transfer is unsuccessful, the execution halts.

The match block checks the provision of the optional parameter, memo. If memo is passed to the transfer function, it binds the value memo to the variableto-print. The print statement emits the bonded variable. If memo was not passed, we write 0x.

At the end of the function, we return a response (ok true) indicating that all went well and the changes made in the function can be committed to the blockchain. A public function must return a response of either success or failure.


(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
    (begin
        (asserts! (> amount u0) err-amount-less-than-zero)
        (asserts! (is-eq tx-sender sender) err-not-token-owner)
        (try! (ft-transfer? fanToken amount sender recipient))
        (match memo to-print (print to-print) 0x)
        (ok true)
    )
)

We are done discussing the two main functions of the FanToken contract, the other functions in the contract are read-only that display the token data.

Testing FanToken in the terminal

We have successfully created a contract, so let's deploy it for testing at the terminal. Navigate to the contracts folder located inside the token-contract folder. Run the code. This Clarinet CLI command loads and deploys contracts in the terminal environment.

clarinet console

This is a nice way of testing your contract manually before deploying. You can execute the contract's methods from the CLI.

To test our mint function, run the code below at the terminal.

(contract-call? .FanToken mint u4000000000 tx-sender)

We are calling a contract named; the dot in front of FanToken it is a shorthand way of representing the principal contract that was deployed. Remember, a contract principal is a combination of the standard principal that deployed the contract and the contract name. We are executing the contract in the context of the deployer account; that's why the shortcut.FanToken works.

The next parameter passed to the contract-call? block after the contract name is the function name, which, in our case, is mint. Then, the parameters of the function are passed after the function name. We are minting 4000 FT (FT token uses 6 digits) for the principaltx-sender.

Execute the code, and you will get a similar output below. A print block was emitted as the tokens were minted and transferred to tx-sender. A response(ok true) was returned from the function, showing that the execution was successful.

We can check the balance of tx-sender by executing the get-balance function.

(contract-call? .FanToken get-balance tx-sender)

Creating the TokenGatedCommunity contract

We shall proceed to create the second contractTokenGatedCommunity. Copy the code below and post it in the TokenGatedCommunity.char file located in the contracts folder.


;; title: TokenGatedCommunity
;; version: 1.0
;; summary: 
;; description:


;; constants
(define-constant contract-owner tx-sender)
(define-constant err-insufficient-token-balance (err u1002))
(define-constant err-getting-balance (err u1003))
(define-constant err-not-the-owner (err u1004))
(define-constant err-token-not-greaterThan-Zero (err u1005))
(define-constant err-unwrap-failed (err u1006))
(define-constant err-already-a-member (err u1007))
(define-constant err-not-a-member (err u1008))

(define-map tokenBalances principal uint)

;; data vars
(define-data-var entryTokenAmount uint u50000000) ;;50 FT


(define-public (joinCommunity) 
  (begin
    (if (is-none (userTokenBalance tx-sender))
       (transferTokenAndJoinCommunity (var-get entryTokenAmount))
      err-already-a-member
    )
  )
)

 (define-private (transferTokenAndJoinCommunity (tokenAmount uint)) 
   (begin 
    (try! (contract-call? .FanToken transfer tokenAmount tx-sender (as-contract tx-sender) none))
    (map-set tokenBalances tx-sender tokenAmount)
    (ok true)
   )
 )

 (define-private (payoutTokens (receiver principal) (amount uint))
     (begin 
        (asserts! (is-eq .TokenGatedCommunity (as-contract tx-sender)) err-not-the-owner )
        (try! (as-contract (contract-call? .FanToken transfer amount .TokenGatedCommunity receiver  none)))
        (ok true)
      )
  )

 (define-public (removeTokenAndExitCommunity)
     (
        let (
            (balance (unwrap! (userTokenBalance tx-sender) err-not-a-member))
        )

        (try! (payoutTokens tx-sender balance))
        (map-delete tokenBalances tx-sender)
        (ok true)
     )
 )

;;public-function
(define-public (setEntryTokenAmount (newEntryTokenAmount uint) ) 
    (begin
        (asserts! (is-eq tx-sender contract-owner) err-not-the-owner)
        (asserts! (> newEntryTokenAmount u0) err-token-not-greaterThan-Zero)
        (var-set entryTokenAmount newEntryTokenAmount)
        (ok true)
     )
)

(define-read-only (userTokenBalance (user principal)) 
   (map-get? tokenBalances user)
)

(define-read-only (isUserACommunityMember (user principal)) 
   (match (map-get? tokenBalances user) bal
     (begin 
       bal
      (ok true)
     )
     (ok false)
   )
)

;;read-only function
(define-read-only (getEntryTokenAmount)
     (ok (var-get entryTokenAmount))
)

At the top of the contract, some useful constants are defined. The contract-owner is set to the contract deployer. Some other declared constant variables are used to represent errors.

A data variable (define-data-var entryTokenAmount uint u50000000) called entryToken is defined, and its initial value is set at 50 FT tokens.

The functionality of this contract;

users send FanToken to the contract, and they are registered in the community; their principal is added to a data-map variable tokenBalances
users can withdraw their FanToken from the TokenGateCommunity contract, and their principal is deleted from the data-map.

Sending tokens to the `TokenGateCommunity` Contract

The public function joinCommunity adds the user to the community if they are not already a member. Let's dissect the function to see how it works

(define-public (joinCommunity) 
  (begin
    (if (is-none (userTokenBalance tx-sender))
      (transferTokenAndJoinCommunity (var-get entryTokenAmount))
      err-already-a-member
    )
  )
)

The function accepts no parameter; inside the begin block, a read-only function userTokenBalance returns a value of an optional from the variabletokenBalances of the user ( caller of the function ). The return value of userTokenBalace could either be a (some unit) if the user principal is on the data-map variable ornone if it is not on the data-map variable.

(define-read-only (userTokenBalance (user principal)) 
   (map-get? tokenBalances user)
)

The if block checks the boolean value of the result from the is-none block. If the result from userTokenBalance is noneis-none block returns true and if the result is (some unit)is-none block returns false.

The if block runs when the user is not already a community member. The private function transferTokenAndJoinCommunity is executed. The function is accepted as a parameter; this is the entry fee used to join the community.

An external contract-call? is made to the .FanToken contract, calling its transfer function. An amount of tokens equal to the parameter tokenAmount is transferred from the user account to the TokenGatedCommunity contract. This transfer is wrapped in a try! block that halts contract execution if the token transfer fails.

Next, the user is added to the data-map , a response of ok is returned to the function caller. The token has been transferred successfully to the TokenGatedCommunity contract, and the user is now a community member.

The remaining portion left to dissect in the joinCommunity function is the else part of the if block. This throws an error stating that the user is already a community member.


(define-private (transferTokenAndJoinCommunity (tokenAmount uint)) 
   (begin 
    (try! (contract-call? .FanToken transfer tokenAmount tx-sender (as-contract tx-sender) none))
    (map-set tokenBalances tx-sender tokenAmount)
    (ok true)
   )
 )

Withdrawing tokens from the `TokenGateCommunity` Contract

This is when the user gets tired of the community and wants to leave. Ideally, they should get their tokens back from the TokenGateCommunity contract and their principal deleted from the userTokenBalancesdata-map.

Let's see the implementation details:

 (define-public (removeTokenAndExitCommunity)
     (
        let (
            (balance (unwrap! (userTokenBalance tx-sender) err-not-a-member))
        )
        (try! (payoutTokens tx-sender balance))
        (map-delete tokenBalances tx-sender)
        (ok true)
     )
 )

The public function removeTokenAndExitCommunity is called by the user to exit the community and get paid their tokens. Inside the function, there's a let block used to save values in a temporary data-binding variable called balance. The unwraps! function unwraps the optional value returned from the read-only function userTokenBalance. If unwrap was successful, the user token balance in the contract is stored in the temp variable balance but if unwrap! encounters a value of none in the function, meaning the principal is not in the tokenBalancesdata-map, it throws an err-not-a-member error.

After retrieving the user token stored by the contract, the private function payoutTokens is called with two parameters of the user principal and the user token amount in the contract. Let's examine the payoutTokens function below:

  (define-private (payoutTokens (receiver principal) (amount uint))
     (begin 
        (asserts! (is-eq .TokenGatedCommunity (as-contract tx-sender)) err-not-the-owner )
        (try! (as-contract (contract-call? .FanToken transfer amount .TokenGatedCommunity receiver  none)))
        (ok true)
      )
    )

The function starts with a begin block, which contains three statements. The first is an asserts! function that checks the equality of the contract principal with the caller; the (as-contract tx-sender) calls a function in the context of the contract and not the wallet principal.

The next statement makes an external call to the transfer function of .FanToken contract in the context of the .TokenGatedCommunity contract. This is necessary to transfer the tokens, as the tokens are owned by the .TokenGatedCommunity contract at this point. We return a response of ok if the tokens were successfully transferred to the recipient.

Finally in the removeTokenAndExitCommunity function, the user is deleted from the tokenBalancesdata-map and a response of ok is returned from the function.

Setting the `entryTokenAmount` value

The function sets the value of the data variable entryTokenAmount. The setEntryToken function accepts a newEntryTokenAmount as a parameter with a type of unit. The first asserts! checks that the contract-ownerconstant is the same as the principal calling the function. The next asserts! performs data sanitation, ensuring that the passed parameter is greater than 0. The value of entryTokenAmount is changed using the var-set function. A response of type (ok true) is returned from the function.

;;public-function
(define-public (setEntryTokenAmount (newEntryTokenAmount uint) ) 
(begin
    (asserts! (is-eq tx-sender contract-owner) err-not-the-owner)
    (asserts! (> newEntryTokenAmount u0) err-token-not-greaterThan-Zero)
    (var-set entryTokenAmount newEntryTokenAmount)
    (ok true)
)
)

Wooh! We have come to the end of creating the smart contracts. You can test this contract the same way we tested the FanToken contract.

Deploying Clarity smart contracts to testnet

Navigate to the settings folder in the Clarity project. The folder contains three files Devnet.toml, Testnet.toml and Mainnet.toml contained inside the contracts folder. These files will contain the seed phrases for the wallet that will deploy the contract in the respective environment of Devnet, Testnet and Mainnet. Devnet.toml is already filled with different wallet seed phrases.

Open the Testnet.toml and replace "<YOUR PRIVATE TESTNET MNEMONIC HERE>" with the seed phrase from the wallet we created earlier.

Move into the contracts folder of the Clarinet project and run the command below to generate a deployment file for the testnet environment.

clarinet deployment generate --testnet --low-cost

This command generates a deployment file for testnet using low-cost fees for the deployment. If we are deploying to mainnet, we change --testnet to --mainnet.

After creating the deployment file, the next step is to apply the file and deploy the contract to the chosen environment. This command applies the deployment:

clarinet deployment apply -p deployments/default.testnet-plan.yaml

The smart contracts are broadcast and deployed to the network. Our contract name is a combination of the principal that deployed the contract and the contract name.

Deploying to devnet

We will also deploy the smart contracts to devnet. Hiro has a wonderful explorer that can be used to simulate and test the functionality of contracts on the devnet. Deploying to the devnet is straightforward. Before proceeding, you should install Docker on your system. If you haven't installed it yet, you can install it from the official page.

If Docker has been installed, open the contracts folder of the Clarity projects at the terminal and run:

clarinet devnet start

Docker will download the containers needed to run the devnet the first time you run this command. It might take a little time, so be patient. Your terminal will look similar to the one below when the devnet is running. Stacks Devnet Explorer runs on localhost:8000.

Keep the devnet terminal running, and let's proceed to the frontend to connect our application to the devnet blockchain.

Creating a NextJS frontend

The smart contracts part of our application is ready. The next step is to create a NextJS frontend that will interact with the contracts. We will use Hiro starter templates for fast iteration.

Navigate to the root folder of your project and create a new folder named frontend. cd into the frontend folder and run the code below to create the NextJS application.

npm create stacks --template .

The stacks tool will walk you through creating a NextJS project. The period (.) after the word --template means we want the NextJS application to be installed in the current directory. Enter frontend as the package name when prompted by the CLI and follow the other prompts to install a NextJS application.

Next, install dependencies by running the command below to install the application dependencies.

npm install

The frontend application is started by running npm run dev. The starter template makes our integration faster as it contains useful boilerplate code, which we can modify to suit our needs.

Let's do a little bit of housekeeping. You can delete the ContractVote.js file found in src/components folder. Delete the content of ConnectWallet.js file located in the components directory and replace it with the below code;

"use client";

import React, { useEffect, useState } from "react";
import { AppConfig, showConnect, UserSession } from "@stacks/connect";
import styles from "../app/page.module.css";

const appConfig = new AppConfig(["store_write", "publish_data"]);

export const userSession = new UserSession({ appConfig });

const trimAddress = (address) => {
  if (address) {
    const start = address.substr(0, 6);
    const middle = ".....";
    const end = address.substr(address.length - 6, address.length)
    return `${start}${middle}${end}`
  }
  return null;
}

function authenticate() {
  showConnect({
    appDetails: {
      name: "Token Gated Demo",
      icon: window.location.origin + "/logo512.png",
    },
    redirectTo: "/",
    onFinish: () => {
      window.location.reload();
    },
    userSession,
  });
}

function disconnect() {
  userSession.signUserOut("/");
}

const ConnectWallet = () => {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (mounted && userSession.isUserSignedIn()) {
    return (
      <div className="Container">
        <button className={styles.buttonConnected} onClick={disconnect}>
          Disconnect Wallet {trimAddress(userSession.loadUserData().profile.stxAddress.testnet)}
        </button>
      </div>
    );
  }

  return (
    <button className={styles.button} onClick={authenticate}>
      Connect Wallet
    </button>
  );
};

export default ConnectWallet;

The addition we made to the file is the trimAddress function used to trim the connected wallet principal. We won't be discussing any CSS styles in this integration.

The ConnectWallet component shows a button asking a user to connect their wallet. Most of the code is boilerplate, and we won't spend time discussing it. The meat of the frontend application will be in the page.js located in the app folder.

Open the page.js file and replace its content following code:

"use client";
import { useEffect, useState } from "react";
import styles from "./page.module.css";
import { Connect } from "@stacks/connect-react";
import ConnectWallet, { userSession } from "/../components/ConnectWallet";

const deployer = "replace-with-the-account-that-deployed-the-project" //acount that deployed the contract
export default function Home() {
  const [isClient, setIsClient] = useState(false);
  const [isQualified, setIsQualified] = useState(false);
  const [userTokenAmount, setUserTokenAmount] = useState(0)
  const [tokensToMint, setTokensToMint] = useState(0);
  const [tokenReceiver, setTokenReceiver] = useState(null)


  useEffect(() => {
    setIsClient(true);
  }, []);


  if (!isClient) return null;

  return (
    <Connect
      authOptions={{
        appDetails: {
          name: "Token Gated Community",
          icon: window.location.origin + "/logo.png",
        },
        redirectTo: "/",
        onFinish: () => {
          window.location.reload();
        },
        userSession,
      }}
    >
      <div className={styles.container}>
        <header className={styles.header}>
          <h1>Token Gated Website</h1>
          <nav className={styles.nav}>

            <ConnectWallet />

          </nav>
        </header>
        <main>


          <div className={styles.inputContainerColumn}>
            <p>Mint FT Tokens</p> &nbsp;
            <input className={styles.input} value={tokensToMint}
              onChange={(e) => setTokensToMint(e.target.value)}
              type="number" placeholder="00"
            />
            <input className={styles.input}
              type="text"
              placeholder="principal to receive the token"
              value={tokenReceiver}
              onChange={(e) => setTokenReceiver(e.target.value)}

            />
            <button className={styles.button}>Mint FT Tokens</button>
          </div>


          {!isQualified &&
            <div className={styles.container}>
              <h3>Join Community</h3>

              <button className={styles.button}
                >Join Community</button>
            </div>
          }



          {/*Token gated content */}

          {isQualified &&

            <div>
              <h1>Welcome to the community of dog lovers Premium content</h1>
              <h3>This part of the website is token gated!</h3>
              <div className={styles.card}>
                <p>Send a transaction to change the entryTokenAmount variable</p>
                <div className={styles.inputContainer}>
                  <input type="number" className={styles.input} placeholder="00" />
                  <button className={styles.button}>Change Entry Fee</button>
                </div>
              </div>



              <div className={styles.inputContainer}>
                <p>Exit Community and claim back your tokens</p>

                <button className={styles.button}>Exit Community</button>
              </div>

            </div>

          }


        </main>
      </div>
    </Connect>
  );
}

The application should look like the one below. At the top of the file, we specified that the file will only run in the client environment, useState and useEffect is imported from react.

Some react state is defined that will be used in the application. Look at the deployer variable; replace this value with the account that deployed the contract. If working with devnet this will be the first account listed in the Devnet.toml file.

The ConnectWallet button was imported, as well as a Connect component from the package @stacks/connect-react. The Connect component manages the user session as they sign out and sign in via their wallets.

The simple UI of the front end will allow a user to mint FanToken, join the community, and exit the community. The isQualified state renders the token-gated portion of the website if its value is true. Let's see how to read contract value from a Clarity smart contract in the frontend application.

Reading values from Clarity smart contracts using Stacks.js

The first function we shall implement reads the amount of FanToken owned by the signed-in user. Copy and paste the code below in the page.js file after the useEffect function.

 import { StacksTestnet, StacksDevnet } from "@stacks/network";
 import { callReadOnlyFunction, standardPrincipalCV } from '@stacks/transactions';

//code removed here

  useEffect(() => {
    setIsClient(true);
  }, []);

const getTokenBalance = async () => {
    const userDevnetAddress = userSession.loadUserData().profile.stxAddress.testnet
    console.log("devNetAddress ", userDevnetAddress)
    try {
      const contractName = 'FanToken';
      const functionName = 'get-balance';
      const network = new StacksDevnet();
      const senderAddress = userDevnetAddress;
      const options = {
        contractAddress: deployer,
        contractName,
        functionName,
        functionArgs: [standardPrincipalCV(userDevnetAddress)],
        network,
        senderAddress,
      };
      const result = await callReadOnlyFunction(options);
      const { value: { value } } = result
      const tokenAmount = +value.toString() / 1_000_000
      setUserTokenAmount(tokenAmount)
      console.log("result => ", tokenAmount + "FT")
    } catch (error) {
      console.log("error => ", error);
    }
  };

//code remove for brevity

The getTokenBalance gets the balance of the user token. This is a read-only function, so we ain't making a transaction. We imported StacksDevnet network from the @stacks/network. If the contract we are working with is deployed on a testnet, we will use the StacksTestnet network constructor.

The connected user wallet is retrieved from the userSession object, and an options object that contains the following properties is constructed;

 const options = {
        contractAddress: deployer,
        contractName,
        functionName,
        functionArgs: [standardPrincipalCV(userDevnetAddress)],
        network,
        senderAddress,
      };

Function arguments have to be converted to Clarity type. The standardPrincipalCV converts the user address to a Clarity principal type. Next, we call the contract, passing the options object we have defined and await the result of the call.

const result = await callReadOnlyFunction(options);

The result is an object that contains the user balance sent from the smart contract we just read. We destructure the result object and divide the value obtained by 100000 to get the token amount, as the FanToken operates internally with 6 digits. Lastly, we update the state using setUserTokenAmount function.

const { value: { value } } = result
const tokenAmount = +value.toString() / 1_000_000
setUserTokenAmount(tokenAmount)

ThegetTokenBalance function is triggered in a useEffect when the user sign in in with the wallet. Add this useEffect code;

  useEffect(() => {
    getTokenBalance()
    isUserACommunityMember()
  }, [userSession.isUserSignedIn()])

Let's define another read-only function that checks if the user is a community member, isUserACommunityMember. Copy and paste the code below in the page.js file.

import {
  callReadOnlyFunction, standardPrincipalCV, ClarityType, AnchorMode,
  PostConditionMode, contractPrincipalCV, uintCV
} from '@stacks/transactions';
//top of code removed. paste after the getTokenBalance function
 const isUserACommunityMember = async () => {
    const userDevnetAddress = userSession.loadUserData().profile.stxAddress.testnet
    try {
      const contractName = 'TokenGatedCommunity';
      const functionName = 'isUserACommunityMember';
      const network = new StacksDevnet();
      const senderAddress = userDevnetAddress;
      const options = {
        contractAddress: deployer,
        contractName,
        functionName,
        functionArgs: [standardPrincipalCV(userDevnetAddress)],
        network,
        senderAddress,
      };
      const result = await callReadOnlyFunction(options);
      if (result.value.type == ClarityType.BoolTrue) {
        setIsQualified(true)
      } else {
        setIsQualified(false)
      }
    } catch (error) {
      console.log("error => ", error);
    }
  };

This function calls the isUserACommunityMember function of the TokenGatedCommunity contract. The function returns a boolean indicating whether the user is a member. The state isQualified is set based on the passed boolean result.

Sending transactions to a Clarity contract using Stacks.js

We will examine how to send transactions to our smart contracts. Previously, we saw how to obtain values from the contract via read-only functions. This section will examine the mintToken function to see how this is done. The mintFunction is used to mint tokens; it accepts a token amount and the receiver address as parameters. The user needs to have some tokens before joining the community, so the mintToken function gives the user free tokens.

const mintTokens = async () => {
    let amount = tokensToMint * 1000_000; //token is 6 digit
    amount = uintCV(amount);
    openContractCall({
      network: new StacksDevnet(), //on testnet new StacksTestnet()
      anchorMode: AnchorMode.Any,
      contractAddress: deployer,
      contractName: 'FanToken',
      functionName: 'mint',
      functionArgs: [amount, standardPrincipalCV(tokenReceiver)],
      postConditionMode: PostConditionMode.Deny,
      postConditions: [],
      onFinish: data => {
        // WHEN user confirms pop-up
        setTokensToMint(0)
        setTokenReceiver(null)
        //on testnet the url will be => https://explorer.hiro.so/txid/${data.txId}?chain=testnet
        window
          .open(
            `http://localhost:8000/txid/${data.txId}?chain=testnet&api=http://localhost:3999`,
            "_blank"
          )
          .focus();
      },
      onCancel: () => {
        // WHEN user cancels/closes pop-up
        console.log("onCancel:", "Transaction was canceled");
      },
    });
  }

Transactions are sent using the openContractCall Stacks.js function. The function accepts as an argument an object that contains the functionName, contractAddress like the callReadOnlyFunction we used earlier to get the token balance. It also contains additional properties like postConditionMode, postCondition , onFinish and onCancel.

The postCondistionMode has a value of PostConditionMode.Deny and PostConditionMode.Allow. PostConditionMode.Denymeans that tokens will not be transferred from the user. This protects the user against malicious contracts, as the transaction will revert if any such token transfer is attempted. The postCodition array sets conditions specifying how many tokens can be withdrawn from the user.

onFinish function is triggered after the transaction has been created; in this example, we open the explorer to view the transaction. onCancel is triggered if the user cancels the transaction. The value of the amount of token we are minting is retrieved from the tokenToMint state, and it is converted to a Clarity type of uintCV, so also the token receiver value is converted to a standardPrincipal and both values are passed to the functionArgs array.

After minting the tokens, we can refresh the page to see our minted token. There are two more transactions to define for this webpage: a transaction function to join the community and another function to exit the community.

Finishing the frontend

The complete code of the page.js function is given below. We define a function joinTokenGatedCommunity and exitTokenGatedCommunity and some other utility functions. The isQualified state regulates access to the token-gated parts of the webpage. isQualified is set based on the value returned from the read-only function isUserACommunityMember.

Adding the complete code to page.js, we will see that there is some restricted parts of our webpage. We can build on this idea to create a more robust web application for token-gated users.

"use client";
import { useEffect, useState } from "react";
import styles from "./page.module.css";

import { Connect } from "@stacks/connect-react";

import ConnectWallet, { userSession } from "../components/ConnectWallet";
import { StacksTestnet, StacksDevnet } from "@stacks/network";
import {
  callReadOnlyFunction, standardPrincipalCV, ClarityType, AnchorMode,
  PostConditionMode, contractPrincipalCV, uintCV
} from '@stacks/transactions';
import { openContractCall } from '@stacks/connect';


const deployer = "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" //acount that deployed the contract

export default function Home() {
  const [isClient, setIsClient] = useState(false);
  const [isQualified, setIsQualified] = useState(false);
  const [userTokenAmount, setUserTokenAmount] = useState(0)
  const [tokensToMint, setTokensToMint] = useState(0);
  const [tokenReceiver, setTokenReceiver] = useState(null)

  const mintTokens = async () => {
    let amount = tokensToMint * 1000_000; //token is 6 digit
    amount = uintCV(amount);
    openContractCall({
      network: new StacksDevnet(), //on testnet new StacksTestnet()
      anchorMode: AnchorMode.Any,
      contractAddress: deployer,
      contractName: 'FanToken',
      functionName: 'mint',
      functionArgs: [amount, standardPrincipalCV(tokenReceiver)],

      postConditionMode: PostConditionMode.Deny,
      postConditions: [],

      onFinish: data => {
        // WHEN user confirms pop-up
        setTokensToMint(0)
        setTokenReceiver(null)
        //on testnet the url will be => https://explorer.hiro.so/txid/${data.txId}?chain=testnet
        window
          .open(
            `http://localhost:8000/txid/${data.txId}?chain=testnet&api=http://localhost:3999`,
            "_blank"
          )
          .focus();
      },
      onCancel: () => {
        // WHEN user cancels/closes pop-up
        console.log("onCancel:", "Transaction was canceled");
      },
    });

  }


  const joinTokenGatedCommunity = async () => {
    try {
      openContractCall({
        network: new StacksDevnet(), //on testnet new StacksTestnet()
        anchorMode: AnchorMode.Any,
        contractAddress: deployer,
        contractName: 'TokenGatedCommunity',
        functionName: 'joinCommunity',
        functionArgs: [],

        postConditionMode: PostConditionMode.Allow,
        postConditions: [],
        onFinish: data => {
          setTokenReceiver(null);
          setTokensToMint(0)
          // WHEN user confirms pop-up
          //on testnet the url will be => https://explorer.hiro.so/txid/${data.txId}?chain=testnet
          window
            .open(
              `http://localhost:8000/txid/${data.txId}?chain=testnet&api=http://localhost:3999`,
              "_blank"
            )
            .focus();
        },
        onCancel: () => {
          // WHEN user cancels/closes pop-up
          console.log("onCancel:", "Transaction was canceled");
        },
      });
    } catch (error) {
      console.log("error => ", error);
    }
  };

  const exitTokenGatedCommunity = async () => {
    try {
      openContractCall({
        network: new StacksDevnet(), //on testnet new StacksTestnet()
        anchorMode: AnchorMode.Any,
        contractAddress: deployer,
        contractName: 'TokenGatedCommunity',
        functionName: 'removeTokenAndExitCommunity',
        functionArgs: [],
        postConditionMode: PostConditionMode.Allow,
        postConditions: [],
        onFinish: data => {
          // WHEN user confirms pop-up
          //on testnet the url will be => https://explorer.hiro.so/txid/${data.txId}?chain=testnet
          window
            .open(
              `http://localhost:8000/txid/${data.txId}?chain=testnet&api=http://localhost:3999`,
              "_blank"
            )
            .focus();
        },
        onCancel: () => {
          // WHEN user cancels/closes pop-up
          console.log("onCancel:", "Transaction was canceled");
        },
      });
    } catch (error) {
      console.log("error => ", error);
    }
  };

  const getTokenBalance = async () => {
    const userDevnetAddress = userSession.loadUserData().profile.stxAddress.testnet
    console.log("devNetAddress ", userDevnetAddress)
    try {
      const contractName = 'FanToken';
      const functionName = 'get-balance';
      const network = new StacksDevnet();
      const senderAddress = userDevnetAddress;
      const options = {
        contractAddress: deployer,
        contractName,
        functionName,
        functionArgs: [standardPrincipalCV(userDevnetAddress)],
        network,
        senderAddress,
      };
      const result = await callReadOnlyFunction(options);
      const { value: { value } } = result
      const tokenAmount = +value.toString() / 1_000_000
      setUserTokenAmount(tokenAmount)
      console.log("result => ", tokenAmount + "FT")
    } catch (error) {
      console.log("error => ", error);
    }
  };

  const isUserACommunityMember = async () => {
    const userDevnetAddress = userSession.loadUserData().profile.stxAddress.testnet
    try {
      const contractName = 'TokenGatedCommunity';
      const functionName = 'isUserACommunityMember';
      const network = new StacksDevnet();
      const senderAddress = userDevnetAddress;
      const options = {
        contractAddress: deployer,
        contractName,
        functionName,
        functionArgs: [standardPrincipalCV(userDevnetAddress)],
        network,
        senderAddress,
      };
      const result = await callReadOnlyFunction(options);
      if (result.value.type == ClarityType.BoolTrue) {
        setIsQualified(true)
      } else {
        setIsQualified(false)
      }

    } catch (error) {
      console.log("error => ", error);
    }
  };


  useEffect(() => {
    setIsClient(true);
  }, []);

  useEffect(() => {
    getTokenBalance()
    isUserACommunityMember()
  }, [userSession.isUserSignedIn()])

  if (!isClient) return null;

  return (
    <Connect
      authOptions={{
        appDetails: {
          name: "Token Gated Community",
          icon: window.location.origin + "/logo.png",
        },
        redirectTo: "/",
        onFinish: () => {
          window.location.reload();
        },
        userSession,
      }}
    >
      <div className={styles.container}>
        <header className={styles.header}>
          <h1>Token Gated Website</h1>
          <nav className={styles.nav}>

            <ConnectWallet />

          </nav>
        </header>
        <main>

          <p>
            User Fan Token Balance: {userTokenAmount} FT
          </p>


          <div className={styles.inputContainerColumn}>
            <p>Mint FT Tokens</p> &nbsp;
            <input className={styles.input} value={tokensToMint}
              onChange={(e) => setTokensToMint(e.target.value)}
              type="number" placeholder="00"
            />
            <input className={styles.input}
              type="text"
              placeholder="principal to receive the token"
              value={tokenReceiver}
              onChange={(e) => setTokenReceiver(e.target.value)}

            />
            <button className={styles.button} onClick={mintTokens}>Mint FT Tokens</button>
          </div>


          {!isQualified &&
            <div className={styles.container}>
              <h3>Join Community</h3>

              <button className={styles.button}
                onClick={joinTokenGatedCommunity}>Join Community</button>
            </div>
          }

          {/*Token gated content */}

          {isQualified &&

            <div>
              <h1>Welcome to the community of dog lovers Premium content</h1>
              <h3>This part of the website is token gated!</h3>
              <div className={styles.card}>
                <p>Send a transaction to change the entryTokenAmount variable</p>
                <div className={styles.inputContainer}>
                  <input type="number" className={styles.input} placeholder="00" />
                  <button className={styles.button}>Change Entry Fee</button>
                </div>
              </div>



              <div className={styles.inputContainer}>
                <p>Exit Community and claim back your tokens</p>

                <button className={styles.button}
                  onClick={exitTokenGatedCommunity}>Exit Community</button>
              </div>

            </div>

          }
        </main>
      </div>
    </Connect>
  );
}

Conclusion

This example application could be built upon to solidify the knowledge gained in integrating Clarity smart contracts with a frontend application.

In this blog post, we learned how to create Clarity smart contracts, fungible tokens, and how to token-gate a webpage using a token. We also learned how to deploy smart contracts to either the testnet or devnet and connect with a front-end to send transactions to the network. I hope you have learned a thing or two from this piece.

Thank you for reading to the end. The source code can be found here.

Farcaster Frames Explained

2024-02-16T14:33:50.652Z

Frames excited enough users to make Farcaster worth their time. To be honest, I wouldn’t say I liked Farcaster at first, as it required installing a native app on my phone. In 2024, when it’s called Web3; why would anyone install a native app?!

At least the Warpcast app works in the browser after completing the registration process, so why not try it? Especially with all the hype around Frames. And when I’m already on it, why not write a few words about it?

So, here it is, yet another Farcaster Frames explainer for you!

What are Farcaster Frames?

Technically, Frames are an extension of the Open Graph protocol (OGP) but a peculiar one, as you can use OGP features just as a fallback and not mix them.

In practice, you use the fc:frame or the og: metatags. This is a bit strange, as it doesn’t allow Frames to re-use much of the OGP functionality (i.e., actually extending it). To be more precise, the only thing Frames has in common with OGP is that you can use both to embed preview images into other apps.

In contrast to the static nature of OGP, Frames are interactive. While they can’t play videos (yet, the protocol is still under development), they allow you to add up to four buttons and an input field to the image. As Farcaster authenticates users with a crypto address, you can use Frames to perform crypto actions like minting NFTs directly from a Farcaster client.

How Do Farcaster Frames Work?

For a Frames developer, Frames consists of the following parts:

A frame definition is like a Farcaster app widget that tells the app what to render and where to send the actions.
A frame server handles the actions received from the app and can consult a Farcaster Hub for validation or additional Farcaster data. Let’s look at examples of both.

Figure 1 illustrates how they integrate with the Farcaster stack.

Figure 1: Farcaster Frames Architecture

Frame Definition

Like OGP, Frames are essentially HTML documents with special metatags. Add at least the two required metatags to a document hosted on a public HTTP server to create a frame.

Defining a Minimal Frame

This is a minimal frame-enabled HTML document:

<!doctype html>

<title>Demo Frame</title>

<meta property="fc:frame" content="vNext" />
<meta property="fc:frame:image" content="https://example.com/image.jpg" />
<meta property="og:image" content="https://example.com/image.jpg" />

It only displays a preview image with a 1:1 or 1.91:1 aspect ratio. Putting the URL for that document into a Farcaster post or cast (the actual name of posts on Farcaster) will display the image inside any Farcaster client that supports Frames.

The og:image tag is required as a fallback for clients not supporting Frames.

Figure 2: Simple Frame

Note: The first frame is cached, so while you must host it on your server, you can’t change it after a user loads it the first time.

Defining an Advanced Frame

You can use some optional metatags to get the interactive part going. Let’s look at a more complex example:

<!doctype html>

<title>Demo Frame</title>

<meta property="fc:frame" content="vNext" />
<meta property="fc:frame:image" content="https://example.com/image.jpg" />
<meta property="og:image" content="https://example.com/image.jpg" />

<meta property="fc:frame:post_url" content="https://example.com/api" />
<meta property="fc:frame:button:1" content="Button 1" />
<meta property="fc:frame:button:2" content="Button 2" />
<meta property="fc:frame:input:text" content="Input" />

The top section is the same as before, but we have new metatags at the bottom.

Let’s start with the fc:frame:post_url, which brings us to the first crucial point. When a user clicks a button, the Farcaster client will send a POST request to the URL in this tag and expects the response to contain an HTML document with a new frame definition. This allows you to change the content of a frame after it is rendered. After every button click, you can display a new frame with a new image, new buttons, and so on.

The fc:frame:button:1 and fc:frame:button:2 tags define the buttons and their labels. Again, when a user clicks them, by default, the frame sends a POST request to the FC:frame:post_url. This request will contain the index of the button.

The fc:frame:input:text tag lets you add a user input to the POST request.

Figure 3: Advanced frame

A frame can only have 4 buttons and 1 input field; however, they can differ in every new frame your server sends in response to a POST request. Also, other metatags allow you to create different button types (e.g., links and redirects) and send each button click to a different server, giving you more flexibility. Find them in the Farcaster docs.

Frame Server

By default, every button click will issue a POST request. Consequently, you must implement a frame server to handle these requests.

The requirements for a frame server are the following:

Has a POST endpoint
Accepts application/json requests
Responds with valid HTML containing Frames metatags
Takes less than 5 seconds to respond

The frame sends a POST request with JSON data that will look like this:

{
  "untrustedData": {
    "fid": 2,
    "url": "https://example.com/",
    "messageHash": "0xd2b…",
    "timestamp": 1706243218,
    "network": 1,
    "buttonIndex": 2,
    "inputText": "hello world",
    "castId": {
      "fid": 226,
      "hash": "0xa48…"
    }
  },
  "trustedData": {
    "messageBytes": "..."
  }
}

Only use the object in untrustedData for uncritical interactions (i.e., don’t mint an NFT) as attackers can change it.

The trustedData includes a Protocol Buffer encoded string you can use to check for authenticity.

Using Untrusted Farcaster Frame Data

A simple frame server that handles untrusted data, built with Express.js, could look like this:

const express = require("express")
const app = express()

app.use(express.json())

app.get("/frame", (request, response) => {
  response.send(`
    <!doctype html>

    <title>Frame 1</title>

    <meta property="fc:frame" content="vNext">
    <meta property="fc:frame:image" content="https://example.com/image.jpg">
    <meta property="og:image" content="https://example.com/image.jpg">
    <meta property="fc:frame:post_url" content="https://example.com/frame">
    <meta property="fc:frame:button:1" content="Next Frame">
  `)
})

app.post("/frame", (request, response) => {
  const { fid } = request.body.untrustedData

  response.send(`
    <!doctype html>

    <title>Frame 2</title>

    <meta property="fc:frame" content="vNext">
    <meta property="fc:frame:image" content="https://example.com/image.jpg">
    <meta property="og:image" content="https://example.com/image.jpg">
    <meta property="fc:frame:button:1" content="Your FID is: ${fid}">
  `)

})

app.listen(3333, () => 
  console.log("Server started on port 3333")
)

The GET endpoint will deliver the first frame that shows an initial image and a button.

The POST endpoint will use the fid from the request as a label for the next button.

Using Trusted Data from a Farcaster Frame

Here, things get a bit more involved. You should use the object inside trustedData.messageBytes to perform critical interactions. It is encoded with Protocol Buffers to ensure integrity, and you must send it to a Farcaster hub for decoding and validation.

Farcaster Hubs

Farcaster hubs are the servers that make up the Farcaster network. They store and validate the off-chain data and store on-chain data on Optimism and Ethereum. You need a hub to validate your frame messages.

Validating Farcaster Frame Data

To use a hub for validation, send a POST request with the trusted data from your frame server to the /v1/validateMessage endpoint of a Farcaster hub.

Inspired by the frames.js framework, a validation request in JavaScript could look like this:

const binaryData =  new Uint8Array(
  request.body.trustedData.messageBytes.match(/.{1,2}/g)!.map(
    (byte) => parseInt(byte, 16)
  )
)

const response = await fetch(
  "http://example.com:2281/v1/validateMessage", {
  method: "POST",
  headers: {"Content-Type": "application/octet-stream"},
  body: binaryData
}).then(r => r.json())

First, we convert the data into a format fetch understands, then send it to our Farcaster hub of choice, which will validate the content and convert it to JSON.

The response from the hub looks like this:

{
  "valid": true,
  "message": {
    "data": {
      "type": "MESSAGE_TYPE_FRAME_ACTION",
      "fid": 2,
      "timestamp": 48994466,
      "network": "FARCASTER_NETWORK_MAINNET",
      "frameActionBody": {
        "url": "https://example.com/",
        "buttonIndex": 2,
        "inputText": "",
        "castId": {
          "fid": 226,
          "hash": "0xa48d..."
        }
      }
    },
    "hash": "0xd2b...",
    "hashScheme": "HASH_SCHEME_BLAKE3",
    "signature": "3ms...PAA==",
    "signatureScheme": "SIGNATURE_SCHEME_ED25519",
    "signer": "0x78f..."
  }
}

According to the Farcaster docs, the hub will validate the following properties:

the fid (i.e., the user FID) is registered
the signer is active and registered to the fid
the messageHash is correct
the signature is valid and corresponds to the signer

Fetching Farcaster Casts

The Farcaster hub won’t check if the castId belongs to an existing cast, or if the frame url matches the embedded URL in that cast. You have to check it manually if needed (i.e., if a frame should only work when it is actually shared.

To load the cast that issued the message, you can ask the trusty Farcaster hubs.

const response = await fetch(
  "http://example.com:2281/v1/castById?fid=<CAST_FID>&hash=<CAST_HASH>"
).then(r => r.json())

The response looks like this:

{
  "data": {
    "type": "MESSAGE_TYPE_CAST_ADD",
    "fid": <CAST_FID>,
    "timestamp": 48994466,
    "network": "FARCASTER_NETWORK_MAINNET",
    "castAddBody": {
      "embedsDeprecated": [],
      "mentions": [],
      "parentCastId": {
        "fid": 226,
        "hash": "0xa48d..."
      },
      "text": "Cast Text",
      "mentionsPositions": [],
      "embeds": []
    }
  },
  "hash": "0xd2b...",
  "hashScheme": "HASH_SCHEME_BLAKE3",
  "signature": "3ms...PAA==",
  "signatureScheme": "SIGNATURE_SCHEME_ED25519",
  "signer": "0x78f..."
}

Fetching Farcaster User Data

Getting user data might also be important for your frame; as you might expect, you get it from a hub.

const response = await fetch(
  "http://example.com:2281/v1/userDataByFid?fid=<USER_FID>&user_data_type=1"
).then(r => r.json())

The response looks like this:

{
  "data": {
    "type": "MESSAGE_TYPE_USER_DATA_ADD",
    "fid": <USER_FID>,
    "timestamp": 83433831,
    "network": "FARCASTER_NETWORK_MAINNET",
    "userDataBody": {
      "type": "USER_DATA_TYPE_PFP",
      "value": "https://i.imgur.com/HG54Hq6.png"
    }
  },
  "hash": "0x327…",
  "hashScheme": "HASH_SCHEME_BLAKE3",
  "signature": "XIT..9Cg==",
  "signatureScheme": "SIGNATURE_SCHEME_ED25519",
  "signer": "0x085..."
}

There are even more endpoints to fetch casts and their parents, so check out the Farcaster docs.

Note: As you get all the information from Farcaster hubs, running your own might be a good idea. Check out the Hubble docs to learn how.

Why Do You Need Farcaster Frames?

If you’ve used social media apps like Instagram (IG), you might have noticed the ads on that platform. They are integrated similarly to regular posts but come with a button allowing some interactions. Frames are similar; it's just that they are more powerful. In contrast to the IG ads, you can have more buttons and an input field, and the buttons can have any custom functionality a server can perform, not just the actions Meta allows.

You can build rich social media embeds for your service that minimize the barriers for your users. While you can define buttons that open a website in a browser, you can use the default POST buttons to let them do interactions without leaving Farcaster.

Since you have cryptographic account information, you can even let them perform authenticated actions on your service. In Web3 terms, that might mean minting or receiving tokens, but depending on how you link the Farcaster ID to your user accounts, this might include any action you could model with changing sets of up to 4 buttons, an input field, and an image.

These limitations might seem drastic, but a command shell is also a limited yet powerful tool.

Summary

Farcaster Frames are an exciting addition to the social media and Web3 landscape. They are more powerful than OGP but not too powerful, and constraints can fuel creativity.

Remember that you need an HTTP server to build frames, so while they might seem like a frontend technology, backend skills are required to get them working, including traffic considerations and hosting costs.

Finally, remember that the Farcaster Frames specification is new and will change quite a bit. A few days ago, they added a limit for data URI images that broke several frames. So, if you consider using Farcaster Frames for critical tasks, ensure that you have a developer at hand who can keep them up-to-date!

Additional Resources

The Frames specification in the Farcaster docs.
The frames.js framework helps you build frames quickly.

Phala offers an IPFS-based, decentralized hosting solution for Frames called FrameHub.
The Hubble docs explain how to host a Farcaster Hub.

What is Quadratic Funding, and How Does it Work?

2024-02-14T13:49:00.118Z

The rich get richer every day, even when it comes to grant programs; however, Vitalik Buterin, the co-founder of Ethereum, thinks that for Web3 to be truly democratic, grant fundraising should also be democratic.

That brought a new dawn, a new way of raising funds that prioritizes the voice and needs of the majority over the minority big-holder investor.

Quadratic funding (QF) is the new way of fundraising in Web3. The time of crowdfunding is over!

In this article, you will learn the aim behind QF and the potential opportunities embedded in it.

Sit back and enjoy reading!

History of Quadratic Funding

Unsplash: Joanna

We must first trace its origins to understand QF (a.k.a plural funding). Ethereum co-founder Vitalik Buterin envisioned it in collaboration with Zoë Hitzig and E. Glen Weyl from the idea of quadratic voting.

The driving force behind this concept was democratizing the grant fundraising process, challenging the narrative that only the wealthy should dictate the flow of financial support.

The journey began with a proposal paper laying the groundwork for a more democratic approach to crowdfunding. It aimed to address the rich-get-richer phenomenon in traditional grant programs, where major donors hold disproportionate influence.

What is Quadratic Funding?

QF is a democratic crowdfunding mechanism designed to ensure fair and inclusive funding for public goods. This approach would benefit public goods such as open-source software, scientific research, and public art projects.

Gitcoin,, a leading QF platform, defines this method as combining modest individual contributions with larger matching sums from sponsors or contributors.

It brings a novel perspective to crowdfunding by valuing widespread support over high donation amounts.

Quadratic Funding: Empowering Small Contributors

Unsplash: Hannah

QF operates on a fundamental principle: it democratically matches funds to benefit small contributors considerably.

This innovative model stands as a pillar of fairness and inclusivity, ensuring that resources for community projects are allocated based on collective support rather than the preferences of a privileged few.

Why does this matter?

QF is like the superhero of crowdfunding. It levels the playing field, ensuring even the smallest donor has a voice. No more one-size-fits-all matching – it's about amplifying community support.

Parties Involved:

Every community member
Large Donors
Grantees (those seeking funding for a cause)

The Quadratic Funding Process Unveiled

Here's how QF works:

1. Create a Matching Pool

Initiating the process involves setting aside a matching pool of funds. This pool catalyzes amplifying individual contributions.

2. Community Support for Donations

The heart of QF lies in community involvement. The platform encourages individuals to contribute to public goods they value, irrespective of the amount. This widens the participation net, making it accessible to diverse contributors.

3. Quadratic Formula in Action

The unique aspect of QF is its application of a quadratic formula. This formula gives more weight to smaller contributions, leveling the playing field. It ensures that projects with more contributors receive more generous matching funds, even if each contributes modestly.

4. Distribution of Matching Funds

The matching funds, determined by the quadratic formula, are then distributed to public goods. This mechanism guarantees a more equitable allocation of funds based on community preferences, fostering an environment where projects gain support not solely based on their size but on their broad appeal.

Practical Example: Mark's Open-Source Project

Consider Mark, a developer with a vision for an open-source project enhancing online privacy. Launching his campaign on a QF platform (Gitcoin), Mark welcomes support from a diverse community.

Even small contributors who believe in his vision significantly impact the project thanks to the quadratic incentives.

For instance, a hundred contributors, each donating $1, could receive more matching funds than ten contributors, each donating $10.

The quadratic formula's magic lies in recognizing the widespread support that Mark's project garners, irrespective of individual contribution size.

This real-world example showcases how QF goes beyond the traditional fundraising model. It empowers projects like Mark's, which may lack backing from major funders, by democratizing the allocation of resources and emphasizing community-driven decision-making.

This way, QF catalyzes innovation and supports projects that resonate with a broader audience.

How Does Quadratic Funding Improve Crowdfunding?

QF improves crowding funding in many ways; here are a few.

Democratizing the Funding Landscape

QF disrupts conventional crowdfunding norms by introducing a democratic and inclusive approach. Unlike traditional methods favoring large donors, this model places significance on the number of contributors.

In essence, it shifts the power dynamic, ensuring that each voice, regardless of financial capacity, plays a crucial role in determining the allocation of funds.

Incentivizing Modest Contributions

The core strength of QF lies in its ability to incentivize a multitude of modest donations.

Doing so breaks away from the trend observed in traditional fundraising, where a limited number of significant contributions from affluent individuals or organizations tend to dominate.

This shift in focus encourages a broader spectrum of supporters, fostering a community-driven ethos where every contributor, irrespective of the donation size, contributes meaningfully to the cause.

Countering Funding Concentration

Traditional crowdfunding often concentrates funds on well-known or already successful projects. QF disrupts this pattern by rewarding projects with widespread support. The quadratic formula matches contributions many people make more generously than those made by fewer individuals. This counteracts the rich-get-richer phenomenon, promoting diversity and inclusivity in the distribution of funds.

Fostering Diversity and Fairness

QF places a premium on community support, resulting in a fairer distribution of resources for public goods. It inherently values diversity in terms of the number of contributors and the types of projects that receive support. Smaller projects, which might not have the backing of major funders but are nonetheless significant to the community, stand to benefit significantly.

This emphasis on fairness and inclusivity sets QF apart as a transformative force in crowdfunding.

Transparency and Community Involvement

QF aligns with the principles of decentralization and community involvement. The transparent nature of the process, coupled with visible fund allocation, builds trust and confidence among contributors. It ensures that decisions are made collaboratively, based on community preferences, rather than being swayed by the interests of a small group of affluent donors.

Benefits of Quadratic Funding

Encourages a Wide Variety of Contributors

QF encourages diverse participation by providing matching funds for small contributions, irrespective of financial resources.

Incentivizes High-Quality Work

It motivates contributors to produce high-quality work, rewarding projects that generate positive feedback from the community.

Reduces Influence of Large Donors

QF lessens the impact of wealthy donors, ensuring a more representative distribution of funds based on community support.

Supports Transparency

Platforms utilizing QF can enhance transparency by clearly illustrating how they distribute donations, building public confidence.

Democratizes Decision-Making

The democratic nature of QF ensures that decisions are made based on widespread community support rather than the preferences of a few affluent individuals.

Demerits of Quadratic Funding You Should Know

Difficulty in Measuring Impact

Measuring impact can be challenging and arbitrary, making it difficult to distribute resources wisely.

Possibility for Abuse

Dishonest individuals may use the system through forged donations or collusion.

Lack of Diversity

Biases and preferences of the larger community may still influence public goods funded through QF.

Need for Infrastructure and Resources

Establishing a QF system requires significant infrastructure and investment, limiting accessibility.

Impact Determination Challenges

The system may need help accurately determining the impact of funded projects, which could make assessing success difficult.

Blockchain Technology and the Future of Quadratic Funding

Looking ahead, blockchain technology is poised to play a major role in improving the effectiveness and efficiency of QF.

Blockchain offers a secure, open, unchangeable record of donations and funding distributions. Smart contracts can automate the funding process, ensuring equitable and transparent distribution of funds.

The decentralization enabled by blockchain can increase the accessibility of QF, supporting smaller, less-resourced groups and fostering the participation of diverse communities.

Tokens representing contributions can streamline fund tracking and transfer, giving donors a tangible representation of their commitment to a project.

List of projects using QF:

Gitcoin
Ethereum
Pomelo
Giveth
Supermodular
Endaoment

Final Thought

QF is a transformative force in crowdfunding, championing community involvement, fairness, and inclusivity. Gitcoin Grants is already rocking this, raising over $4 Million in Ethereum communities. As it continues to gain traction, its potential impact on public goods projects. While challenges exist, the innovative nature of QF positions it as a dynamic and evolving model with promising prospects. Its uniqueness lies in prioritizing the number of supporters rather than the highest monetary value.

Say goodbye to traditional crowdfunding: QF is the innovative way forward in Web3.

Frequently Asked Questions (FAQs)

What principle underpins QF?

QF prioritizes widespread support over substantial donations, fostering a democratized crowdfunding process where community participation takes precedence.

How does blockchain technology enhance the effectiveness of QF?

Blockchain is the cornerstone by providing a secure and transparent ledger for recording donations.

Simultaneously, smart contracts automate the intricate funding distribution process, thereby increasing operational efficiency and mitigating the risks associated with potential abuse.

What are the primary advantages associated with QF?

QF offers a multifaceted array of benefits. It encourages a diverse spectrum of contributors and acts as a catalyst for high-quality work.

Additionally, it diminishes the disproportionate influence of large donors, promotes transparency in fund allocation, and embodies a democratic decision-making approach.

What challenges does QF encounter?

The challenges encompass measuring impact, mitigating the potential for abuse, addressing the lack of diversity in funded projects, securing the necessary infrastructure and resources, and accurately determining the effect of funded initiatives. Each presents a nuanced aspect contributing to QF's complexities in its implementation and sustainability.

Crafting Beautiful Light Art with Figma and Midjourney

2024-01-22T09:03:25.962Z

One of the most overlooked features of Midjourney is the ability to include images in your /imagine prompt. This gives you the power to influence a prompt's basic visual structure. The more details this image has, the more it will influence your result.

Recently, I have been using very simple sketches created in Figma to influence my Midjourney prompts, and the results are amazing.

First, you can do this with Photoshop, Illustration, Canva, or other tools—even drawn sketches. However, for this tutorial, we'll be using Figma. If you want to learn more about Midjourney, check out my Beginner's Guide and Complete Guide to Image Effects.

Step 1: Background

Let's get started by creating a frame in Figma with the same shape as the image we want to make. In this case, we are using the 16:9 format and painting it with a dark tone, as we want our future image to be set during the night.

Step 2: Shapes

Then, draw a shape - a line, circle, square, or anything you like!

As we want to create an image of a light portal for this guide, we draw a shape that looks like an uneven circle. You can do that by using two circles and the "Subtract" feature, or just make a circle of one color and add another on top with the same color as your background.

Step 3: Effects

Let's add a cool glow effect. Add layer blurs to the shape. You can duplicate the shape a few times and use blurs with different values to make it look 3D. Once you're happy with its appearance, export the image as a PNG and bring it to the Discord of Midjourney.

Step 4: Prompting

Now, let's start building the prompt in Midjourney (for the basics, check out this guide.) Start by adding the image link. Midjourney allows you to add images to a prompt by pasting in a URL. Then, describe what you want the light to do in the picture. You can design the rest of the prompt however you like. In this example, we will be using the following prompt:

Cinematic Medium Shot, mysterious human, circular portal in an alien wasteland leading towards a nebula, in the style of biblical drama, monumental figures, voluminous mass --ar 16:9 --iw 0.5 --v 6 --style raw

What is the IW in Midjourney?

It's the image weight parameter --iw. It's used to adjust the importance of the image vs. text portion of a prompt. The default value is used when no --iw is specified. Let's try playing with three different values (0.9, 0.5, and 0.9) and see the results:

![Cinematic Medium Shot, mysterious human, circular portal in an alien wasteland leading towards a nebula, in the style of biblical drama, monumental figures, voluminous mass Midjourney](https://cdn.hashnode.com/res/hashnode/image/upload/v1705584550255/7e5d9281-b42c-4335-8ac2-a6c10ba3af18.png align= "center")

A weight of 0.9 is very heavy in our prompt. Let's reduce it a little bit.

Weight 0.5 is better. Maybe we can push it a little bit more?

Weight 0.1 is so much better.

That's it! You're done!

You can use the same technique to experiment with different shapes, colors of light, or even camera angles and combine them with various prompts.

I hope this tutorial has been helpful and has given you a new set of tools to explore.

As mentioned before, there are many tools out there for creating these light shapes, but Figma is my favorite, and the best part is it's free for anyone to use!

Thanks for reading!

Hi👋 I'm Erik, a product designer by day and AI storyteller by night.
I've always been crafting stories in my dreams, and now I feel powered by Generative AI tools to make them a reality.

NEAR Chain Abstraction Explained

2024-01-19T09:03:25.382Z

Web3 gives users more control over their data and payments. Still, we pay for these benefits with increased technical and UX complexity. In recent years, blockchain ecosystems have tried to improve onboarding to get a hold of the UX part, but as many new chains sprouted, the technical complexities grew with them.

Account abstraction solves key management quite nicely. When a smart contract can decide when TXs are valid, nobody needs to juggle keys anymore, but wouldn’t it be nice if we could abstract away the different chains altogether? NEAR leverages account abstraction, modular data availability, cross-chain liquidity networks, and composable decentralized frontends for chain interoperability—one account for all chains.

This article explains what chain abstraction means in practice and how NEAR achieves it.

What is Chain Abstraction?

Chain abstraction lets you sign and transact on multiple blockchains with one NEAR account. Instead of creating an account for each chain and managing multiple seed phrases or keys, you create one NEAR account and let it take care of the keys and sign for you. NEAR calls the storage of keys for multiple chains in one NEAR account “Account Aggregation”.

NEAR even allows you to hide all blockchain-related information from users. As NEAR supports linking OpenID Connect accounts to NEAR accounts, account abstraction allows using a simple email login to transact on multiple chains simultaneously.

The unique selling point is that no bridge smart contracts are involved; you do all your transactions on the target chain. For example, a DEX that uses chain abstraction could swap Bitcoin to Ethereum directly since the DEX’s keys that manage the funds on their respective chain are all part of a single NEAR account.

Check out our chain abstraction introduction workshop!

https://www.youtube.com/watch?v=IjRUYxioZLo

How Do NEAR Accounts Work?

Before diving into chain abstraction, you should understand NEAR’s account system, as everything flows from there.

One Account - Many Keys

Each big layer 1 blockchain network has its specialty. NEAR’s killer feature is its account system, which allows you to manage and rotate multiple keys in one account with a human-readable name.

Your account name or “address” could be example.near, so everyone who knows it can send you tokens. However, you could create a key for every smart contract you use to limit the damage if one of these keys gets stolen. As only keys that are currently active in your account can sign new transactions, you can replace one key for one smart contract, keep the keys for all the safe smart contracts, and keep using your account name. Figure 1 illustrates the difference between EVM and NEAR accounts.

Figure 1: EVM and NEAR account comparison

On EVM chains, you derive an address from a public key, which, in turn, is derived from a private key. Private keys are usually deterministically generated from a seed phrase, so a user doesn’t have to remember all keys.

As EVM chains handle all assets via an address and each address only has one key pair, you can’t rotate these keys easily. A new key pair means a new address and a new address requires moving all assets from the old address to the new one.

NEAR uses account IDs like addresses on EVM chains. NEAR supports implicit accounts, which work similarly to the EVM addresses. Yet, named accounts are where NEAR shines. In the case of named accounts, you don’t derive these IDs from public keys; you store the public keys in the account. Seed phrases are also supported to generate keys. Think of it as ENS built into the protocol.

NEAR handles all assets via an account ID, but since it isn’t directly related to a key pair, you can rotate keys without changing your “address”—no need to move your assets to the new address when you get a new key.

There are two types of keys in a NEAR account:

1. FullAccess Keys

You use them to manage the account by creating and deleting keys, calling smart contract functions, and even deleting the whole account. A FullAccess key gives admin access to an account.

2. FunctionCall Keys

They are light versions of FullAccess keys. A FunctionCall key can call the functions of one smart contract. You can also limit which functions a key can call and set an allowance of funds the key can transfer. If a FunctionCall key gets leaked, you can replace it with a new one.

Support for OpenID Connect and Recovery

Another nice feature (albeit not part of the account system but built on top) is the support for OIDC accounts. With the FastAuth SDK, you can build an email-based authentication flow that creates NEAR accounts in the background and relays transactions via your server. The SDK generates a FullAccess key (controlled by NEAR MPC nodes) to manage and recover the account.

Human-readable account names, key rotation, email logins, and account recovery make NEAR a powerful platform. Consequently, leveraging these features on other blockchain networks would greatly improve the Web3 space.

How Does NEAR Chain Abstraction Work?

Now that you understand NEAR’s account model let’s look at chain abstraction.

As mentioned, chain abstraction lets you sign and transact on multiple chains with one NEAR account. If required, you can even hide all blockchain information from a user.

These are the five features that enable this marvel:

OIDC accounts can control NEAR accounts.
Relay servers can subsidize gas fees.
Accounts on NEAR can hold multiple keys.
Support for MPC key generation functions for other chains (i.e., account aggregation)
A frontend hosting platform that connects the keys on NEAR with libraries that connect to other chain networks.

Since you already learned about the account model and the FastAuth SDK, we will check out points 4 and 5.

MPC Key Generation for Multiple Chains

NEAR allows the storage of multiple keys in one account, but obviously, only the public keys are stored there to enable the network to verify your signatures. The private keys are usually stored locally; you should never upload private keys anywhere!

NEAR wanted to go beyond abstracting multi-chain interactions; they tried to hide all blockchain complexity from users. They created a multi-party computation (MPC) node network for private keys. These nodes use threshold cryptography to hold only parts of each key and can sign messages for the user without one node knowing the full key. This shared custody prevents nodes from using your private key without the consent of multiple other nodes in the network. This feature is called Chain Signatures.

When a user wants to sign a message, each node can use a part of the private key to create a partial signature and send it to the user, who then assembles it into a full signature. You can see the process in Figure 2; each node only has a part of the private key and only generates a part of the signature.

Figure 2: NEAR MPC signing process

These MPC nodes got a recent update that allows them to generate keys for EVM chains and Bitcoin, enabling users to sign transactions outside of NEAR.

Layer 2 Data Availability

To verify any proof, you need to see when the transactions happened and be able to reconstruct the state. With NEAR’s Data Availability layer, you can publish your data on decentralized infrastructure for a fraction of the costs on chains like Ethereum or Celestia. See Figure 3 for a cost comparison.

Figure 3: Data availability cost comparison

Part 3 of our chain abstraction workshop is about data availability.

https://www.youtube.com/watch?v=kpwAi0YMhv4

Frontend Component Hosting

Now that all the pieces are in place, we must connect them. That’s where the Blockchain Operating System (BOS) comes into play. Figure 3 illustrates how the BOS fits into the picture.

Figure 3: The BOS architecture

The BOS platform manages onchain frontend components.

With the BOS Loader, you can fetch built-in components stored on the NEAR chain and reuse them in your application. You can also create your own components and store them on NEAR; there is a handy online IDE to get you started. Each component can access website and blockchain data via the BOS API. A nice extra here: When building a NEAR component, you have components from the Radix library implicitly available, so you don’t have to start from scratch.

NEAR components and the FastAuth SDK form the glue between your users and the blockchain ecosystem. Login with email, let MPC nodes sign transactions for your chain of choice, and then submit them via a relay server.

Part 2 of our chain abstraction workshop series is about building composable and decentralized frontends!

https://www.youtube.com/watch?v=pk8QkBqafm4

Future Outlook

NEAR has some exciting features in the pipeline that will enable smart contracts to serve even more use cases.

Encrypted Onchain Content

Chain signatures (i.e., signing with MPC nodes) allow anyone to communicate securely with a smart contract by depositing an encrypted payload and then having that content re-encrypted and sent to a third party.

In theory, this can be used for MEV mitigation, assuming we can have encrypted pools of transactions that miners can’t see before they need to be executed. Users send encrypted bids to the chain, and when the bid closes, the network nodes will decrypt the bids and evaluate them synchronously. This enables private Dutch auctions and more efficient trading with less frontrunning or slippage.

Smart Contract Owned Domains

DNSSEC can verify that a smart contract approved everything served from your domain. This gives users the transparency to ensure that a genuine frontend serves the application and the ability to vote on the changes to the frontend rather than just the backend. Everything is versioned.

Omnichain Liquidity

Efficient decentralized economies need efficient and liquid markets so users don’t suffer from random slippage when transacting. Orderly’s decentralized liquidation engine improves the security of derivative trading.

Zero-Knowledge WASM Prover

To push the boundaries of computing beyond blockchains, the NEAR Foundation and Polygon Labs are embarking on a journey to build a zero-knowledge prover for WebAssembly blockchains. This project is still in development.

Chain Signatures Bounty

Do you have an idea for an awesome use of chain signatures?

NEAR offers a 2,000 USDC bounty for the best implementation of chain signatures!

Summary

NEAR wants to be the blockchain operating system, and they are on a good trajectory. With account aggregation, their account model is superior to that of EVM chains, and bringing it to other chains is a boon for the whole blockchain ecosystem. If they can pull chain abstraction off, they could become valuable partners for every DApp creator.

With their onchain component hosting with several built-in components out-of-the-box, they already save developers quite some time, but with FastAuth, MPC key management, and relayers, they could make chain bridging a thing of the past.

Additional Resources

Our chain abstraction workshop series

NEAR Tutorials

NEAR Tools

Other

Awesome List of NEAR resources

Unleash the Power of DeFi on Bitcoin

2023-12-05T15:40:01.333Z

If you've been building on Ethereum and EVM-compatible chains and yet are intrigued by the potential of Bitcoin, this post is for you. We will talk about Stacks, a Bitcoin layer 2, and how it will unlock $500B+ of Bitcoin liquidity for everyday apps.

Since 2020’s DeFi Summer, we have seen an explosion of smart contract-enabled applications and user experiences—DEXs, AMMs, lending protocols, NFT marketplaces, and more—that now define Web3 and crypto.

However, Bitcoin has not seen this innovation because building on Bitcoin is hard. Bitcoin Script is an incredibly limited language. That makes Bitcoin very secure—great for a store of value and digital currency—but it comes at the cost of programmability. You can't build apps and smart contracts directly on Bitcoin, but that is changing.

We've seen a renewed interest in building on Bitcoin in the past year. From the ordinals protocol introducing Bitcoin-native NFTs to BRC-20 bringing fungible tokens, a wave of innovation is happening on the Bitcoin blockchain, and that doesn't even touch on the innovation happening on Bitcoin layers, ranging from rollups to sidechains to Lightning payment channels to Stacks, the largest Web3 project on Bitcoin. The Bitcoin Halving is just around April 2024, and there’s never been a better time to start building on Stacks.

Stacks: A Bitcoin Layer 2 Network

Stacks is a layer 2 network for Bitcoin with a unique consensus mechanism called Proof of Transfer, enabling it to settle on Bitcoin periodically. Stacks builds on Bitcoin’s security while allowing smart contracts to leverage the same. And coming in 2024, the ecosystem is working on a major upgrade that will bring sBTC, a decentralized, 1:1 Bitcoin-backed, and fully programmable BTC asset, to the ecosystem.

Stacks is a blockchain that extends the functionality of Bitcoin without modifying its core protocol. Satoshi Nakamoto once described this in a forum post: “a completely separate network and separate blockchain, yet shares computational power with Bitcoin,” increasing the total strength and capabilities of the Bitcoin network.

The Stacks Opportunity for Early Builders

Stacks has already brought the innovation of Web3, NFTs, and DeFi to Bitcoin by creating a smart contract layer 2. With the Stacks blockchain upgrade coinciding with the Bitcoin Halving in spring 2024, the Stacks network will soon have a decentralized, programmatic Bitcoin asset: sBTC. You will be able to do everything you can on Ethereum on the Stacks layer 2 with BTC.

Stacks features include:

Moving BTC in and out of the Stacks layer 2 in a decentralized way.
Unlocking BTC for billions of users that can’t use the Bitcoin layer 1.
BTC deployed into many DeFi applications that can’t use layer 1.

You can be one of the pioneers since it's still early—around 200 devs are building in Stacks today, a far cry from Ethereum’s 5,700. However, you're building on the strongest foundation in crypto: the most secure, largest, oldest, and decentralized blockchain that enables you to tap into over $500B of Bitcoin liquidity. This early stage presents a one-of-a-kind opportunity for developers.

Clarity: The Smart Contract Language for Stacks

Stacks uses the Clarity smart contract language to build the next generation of Bitcoin apps.

Clarity is a LISP-like language that gives Stacks developers a direct way to read and, with sBTC next year, write transactions to Bitcoin, unlocking countless additional use cases. It's predictable and secure, making it an ideal choice for high-stakes code where a single bug can cost users billions. Clarity is deterministic—you know where your code will terminate before you execute it, and you can statically analyze your work as you go.

In the diagram below, you can inspect the two languages executing the same functionality, a simple counter smart contract, side-by-side:

We compare the two languages more thoroughly on the Hiro blog.

Fear not if you aren’t keen on learning a new programming language. With the network’s next upgrade coming in 2024, Stacks allows devs to use other popular smart contract languages like Solidity and Rust alongside Clarity in the future.

The Future: sBTC

The next billion users need help to onboard onto Bitcoin currently. Fees are too high, blocktimes are too long, and BTC is not programmable. That’s why there have been many attempts at making a “wrapped Bitcoin” asset.

There is a long history of these wrapped Bitcoin assets. sBTC is different, leveraging Stacks’ unique design to create a decentralized, open-membership set of signers that power deposits and withdrawals of Bitcoin to the Stacks blockchain—instead of a closed-membership set of custodians like a single company or a handful of “bridge nodes”.

Read here about sBTC and how it fulfills its trust-minimized, decentralized promise of a programmatic Bitcoin asset.

Learn to build on Stacks with Clarity today!

Conclusion

Stacks represents a unique opportunity for DeFi and Web3 developers. It allows you to leverage the security and decentralization of Bitcoin while enjoying the flexibility and programmability of smart contracts on a Bitcoin layer 2 network.

With Stacks, you're not just building on any blockchain; you're building on Bitcoin, the most secure, largest, and decentralized entity in crypto. So why wait? Start building on Stacks today and be part of the future of DeFi.

Join the Stacks Discord and sign up for the Stacks DevNTell on December 15th—see you then!

Dev'n'Tell

We're also live on Dev'n'Tell, December 15th at 16:30 UTC!

So, sign up!

My Journey from Newbie to Hackathon Champion

2023-11-01T12:26:19.754Z

I was sitting in my bedroom, watching Silicon Valley, episode S4E1, when Russ asked Richard what the one thing he would build if he had unlimited time and resources. His answer was "a decentralized internet." And I was like, what the heck is that? That would be your reaction when you first heard about this fancy term.

I had always been interested in computers and coding, and I had built all sorts of things, from Discord bots to Python scripts to simple WordPress sites and games. But after hearing about the decentralized internet, I knew that's what I wanted to focus on.

Gm gm! My name is Vedant, and I'm a developer and technical writer. From the beginning, I've been passionate about creating things, just going out there and building stuff. Still, I never thought I could do something as ambitious as making a "decentralized internet".

I started reading books and articles about blockchain technology and building small projects from various boot camps. The more I learned and built, the more excited I became. Then, one day, I had an epiphany: I wanted to be a Web3 developer.

Here we are now; I've been building in the Web3 space for about a year. However, as I realized it takes a lot of work to keep up with the ever-growing number of new product launches, I wanted to join a developer community where I could learn from experienced developers.

I heard many good things about Developer DAO through Lens Protocol and Nader Dabit. I was particularly impressed by the DAO's vast developer community and its Dev-n-Tell sessions.

I immediately got some CODE tokens and joined the DAO 🚀

How I Started With Hackathons

I'm unsure if it's my competitive spirit or my love of free pizza, but I've always been drawn to hackathons. My first hackathon was Ethos, a completely offline event mostly oriented toward cybersecurity but also had a blockchain track. Me and my friend went there as a team, and to my surprise, we were the only team building in our track.

That's when we questioned ourselves: Are we too early? Is there any point in doing all this?

But we persevered and built a simple crowdfunding application with NFT rewards. We won that track, but the experience could have been better. I didn't learn much from the hackathon and started discovering developer clubs. This was the time when I joined Developer DAO, and my hackathon journey began.

Not all hackathons go as smoothly as you might have thought; they can also be challenging, especially if you're new to hackathons or coding.

One of the biggest challenges I faced when I first started participating in hackathons was the documentation. The documentation for new technologies and products can be confusing, especially if you're unfamiliar with them. Sometimes, the documentation is outdated and doesn't match the current version of the technology or product. This can lead to a lot of frustration and wasted time.

Another challenge I faced was the need for developer support. Not all hackathons have a large developer community. This can make it difficult to get help when you get stuck. And when you're on a tight deadline, every minute counts.

Finally, bugs are always a challenge in software development, but they are especially frustrating during a hackathon. When you're under pressure to deliver a working product in a short amount of time, every bug feels like a major setback.

How I Got Better at Hackathons

I remember the first project I made for a Developer DAO hackathon: a simple newsletter service that sent Web3 onboarding emails using Mailchain. It was a really simple project, but after seeing other people's projects, I asked myself, "How do these people build such amazing things?"

I felt like I was in a bad situation. I didn't know how to learn how to make those types of things. But then I realized that the obvious path was to check out their projects and see how they had implemented things. I could understand their thought process while they were doing those projects.

My major takeaway from that hackathon was: Learn from other people's projects. It gives you a great idea of how to make amazing projects yourself.

For example, if you've participated in an ETH Global Hackathon after the results are declared, you can see all their projects on their showcase page with source code and live demo. Just try them out and see what interests you. Play around with them. This will give you more creative thinking ideas for projects, and you will also learn how to do things that you thought were previously not doable.

Another thing I learned after giving hackathons is that most people don't continue with their projects after hackathons. This was the same thing for me at first. It's like the meme of half-eaten apples and my uneaten projects.

But if you believe in your project, continue it! This is a great thing to do after a hackathon. Just rewrite things and make your hackathon project more optimized, more organized, and better in general. You'll learn various new things just by thinking of alternative approaches to implement a single feature.

Writing Technical Articles for Hackathons

If you have a simple hackathon project or you don't feel like building a full-fledged project, writing a technical article is a great option. Some hackathons offer a separate track for technical articles, such as the Mailchain, MINA, and Phala tracks at Developer DAO hackathons. They are a great way to grab some additional prizes and recognition.

To write a technical article for a hackathon, simply choose a topic related to your hackathon project and write a concise tutorial on how to build it.

I've written a few technical articles for hackathons, and it's a great way to learn the product on a much deeper level. When you write a technical article, you have to explain the product to your audience, which forces you to research it and understand how it works. This can be helpful, especially if you're new to the product or technology.

Another benefit of writing technical articles is that it's a great way to share your knowledge. I've received a lot of positive feedback from people who read my articles and found them helpful. It's a great way to connect with other developers and learn from them.

At one hackathon, I decided to write an article about how to use a new blockchain platform called Mina Protocol. I had never used Mina before, so I had to do much research. I wrote an article on "How to Build a zk-Airdrop App with Mina Protocol", and I won a prize for the best technical article at the hackathon!

So, If you're looking for a way to contribute to a hackathon without building a full-fledged project, writing a technical article is a great way to learn new things, share your knowledge with others, and even win prizes!

Highlights from the Hackathons I Won

I've been in Developer DAO for almost six months and have participated in three hackathons. It's been a great experience, and I'm proud to say I've won prizes in all of them. Here's a small overview of each hackathon and my experience.

Mailchain Hackathon

This was my first Web3 hackathon and my first DAO hackathon. I built a simple Web3 newsletter mail sender where once a person joins a newsletter, they are sent a welcome Web3 mail using Mailchain directly to their Ethereum address.

While doing the project, I also wrote a technical article on the implementation and how to use Mailchain. It's a great way to learn more about the technology and share your knowledge.

Mina Hackathon

My second hackathon was the Mina Hackathon. This time, I was hacking with a friend, Peter, a Developer DAO member. This hackathon was more challenging because Mina doesn’t use EVM but utilizes zkSNARKs to maintain a constant-sized blockchain. So, we needed to familiarize ourselves with a new stack.

In that hackathon, Peter and I tried to build a job credential verifier called zkTalents with GitHub activity and other off-chain data using oracles. We could implement the logic and SnarkyJS contracts and run them successfully, but we failed to integrate them with our front end because of the complexities with web workers.

Despite this setback, we still managed to secure third place in the hackathon for the implementation we did. Apart from that, we both won prizes for technical articles.

The takeaway from this is that it's okay to fail or not do things that you had planned earlier. It happens as hackathons are limited-timed events. Just try your best and learn from your mistakes.

Phala Hackathon

The Phala Hackathon was the most recent hackathon I participated in. This hackathon was divided into two parts: the Early Lens Hackathon and the Main Phala Functions Hackathon.

For the first part of the hackathon, I made a threshold-based roles website using Lens API and OpenZeppelin roles. It lets you have different roles based on your Lens followers, similar to Discord roles but on-chain. I even won second place for that!

For the second hackathon, I was feeling a little creative. For a long time, I wanted to build a Web3 game, and this hackathon let us do that. We could use any data worldwide, so I thought, "Let's make a game!"

After some brainstorming, I came up with the idea of making a crypto betting game using real-time crypto data. We're all amazed by the real-time ticking charts for different tokens, so I recreated them using Binance WebSockets and built an entire game. I won the "Phat" sub-prize for the project.

So, sometimes, you should have fun in hackathons. Build what you want and push your limits.

My Strategy for Winning Hackathons

There is no one-size-fits-all strategy for winning hackathons, but the one I'm about to share has served me well so far. I call it the 3 a.m. Process because I mostly come up with my best ideas late at night.

1. Brainstorming the Idea

The first step is to brainstorm ideas. Think about the basic features you want your product to have. Start with some basic ideas that you can build quickly. Then, think about what you use in real life, like messaging, social media, or payments, and how your product could improve them.

The more you discover other people's ideas and research the product, the better your creative juices will flow. So, go to other hackathon pages and see what other people have already built to take inspiration for projects. Think about something that you could implement based on them.

2. Validating the Idea’s Feasibility

The most important step in the process is validating your idea. Once you have brainstormed a project idea and are happy with it, you must ensure the implementation is feasible. You have to think about every interaction in your project and think, "Is it possible?"

When validating your idea, be sure to think outside the box. Don't be afraid to challenge the status quo.

I like to use FigJam or some other flowcharting program to make a user flow for my project. This lays out the entire flow of my project and gives me a clear path to follow. For individual actions, I can see if they're possible or not. I can also use this to decide my tech stack and plan out my features in the app.

3. How to Start Hacking

Once you have everything planned out, you need to start working on your idea. Hackathons are typically short-timed events, ranging from 36 hours to a week, so you must use your time efficiently.

Leverage Starter Kits, SDKs, and Frameworks

Starter kits are a great way to save time and get started quickly. They provide you with a pre-built foundation that you can use to develop your app. I have a specially set-up starter kit that I use for myself, which has certain technologies and UI libraries that I'm most comfortable with. Everyone should have a similar starter kit for themselves because everyone has different interests in tech stacks and different preferences.

Another tip is to use well-known SDKs and frameworks in your projects. This way, if you get stuck, the answer is already out there on the internet.

Take Regular Breaks

If you feel lost or drained during the hackathon, don't be afraid to take a break. Go outside, touch some grass, have coffee, and clear your head or talk to a friend. Hackathons can be stressful at times, but they can also teach you a lot about how to build things quickly and test your patience.

Wrapping Up

Wooh! That was a long journey, but we made it. We covered a lot of ground, from what hackathons are to how to win them and everything in between.

New chains and protocols are popping up every day, and new ERC standards are coming out all the time. It can be tough to keep up with it all. But hackathons can be a great way to learn about new protocols and products and to stay ahead of the curve.

And let's be honest, who doesn't love fat prizes and swag? Hackathons are a great way to challenge yourself, build something cool, win a prize, and make precious memories.

If you're new to hackathons, Developer DAO is a great place to start. Hackathons are happening constantly, and the community is incredibly supportive and welcoming.

Until next time...and remember, WAGMI forever!

How to Deploy Your Own Hyperlane on Polygon zkEVM

2023-10-02T09:40:51.605Z

gm gm gm!!!

New chains are popping up by the minute, so getting liquidity there is a burning issue. Hyperlane tries to solve this with permissionless bridges. Hyperlane is a permissionless protocol, which means you can deploy your own Hyperlane on any chain without asking the core team. In this guide, you will learn how to deploy Hyperlane on Polygon zkEVM Testnet, Polygon Mumbai Testnet and Sepolia.

There are five steps we need to follow so LFG🚀

Prerequisites

Yarn
Git and GitHub knowledge
Understanding of blockchain
Optional: Solidity experience

1. Setting Up the Keys

Deploying Hyperlane includes smart contracts, validators, and relayers, each requiring a key pair.

The Deployment Keys

To deploy smart contracts, you must have a key pair with the funds for all the chains you will be deploying.

To create the keys, follow these steps:

Open your Terminal and enter the following command
```
  cast wallet new
```
This will generate new keys for you, which will look something like this 👇🏻

⚠

THIS IS A TESTING WALLET.
Save your public address and private key.
Fund your address with the tokens of all the networks.
- For tokens on Polygon zkEVM Testnet and Polygon Mumbai Testnet, use Polygon faucet.
- For tokens on Sepolia, you can use the Alchemy faucet.

The Validator Keys

This tutorial will use the default Hyperlane's Multisig ISM. Multisig ISM is a module that takes several signatures from validators before completing the transaction. We use 4 addresses with the threshold 1.

Copy any 4 of your public addresses for later use.

Note: Make sure to have a private key secured for the public addresses you use. You can generate key pairs using the above method.

2. Cloning the Deploy Repository

The Hyperlane team provides you with a repository that you can use to deploy Hyperlane on your preferred chain.

Follow these steps to set up the Hyperlane deployment repo:

Open your terminal at your preferred directory.

    git clone https://github.com/hyperlane-xyz/hyperlane-deploy.git

```
    cd hyperlane-deploy
```
```
    yarn install
```

3. Adding a Custom Chain to Hyperlane

Hyperlane provided a few chains in the SDK. To add a chain missing from this list, follow these steps:

Open config/chains.ts, where you will find the configuration example for adding new chains.

Add the following configuration for the Polygon zkEVM Testnet:

    polygonzkevmtestnet: {
      name: 'polygonzkevmtestnet',
      chainId: 1442,
      protocol: ProtocolType.Ethereum,
      nativeToken: {
        name: 'ether',
        symbol: 'ETH',
        decimals: 18,
      },
      rpcUrls: [
        {
          http: 'https://rpc.public.zkevm-test.net',
        },
      ],
      blockExplorers: [
        {
          name: 'Polygon Scan',
          url: 'https://testnet-zkevm.polygonscan.com',
          apiUrl: 'https://api-zkevm.polygonscan.com/api',
        },
      ],
      isTestnet: true,
    },

4. Adding the Validator Keys

We will use the default Multisig as our Interchain Security Module.

Follow these steps to set up the keys:

Open config/multisig_ism.ts. You will find the configuration example for adding new chains and their keys there.

Add the keys for your validator:

    polygonzkevmtestnet: {
      threshold: 1,
      type: ModuleType.LEGACY_MULTISIG,
      validators: [
        '0xabcabcabcabcabcabcabcabcabcabcabcabcabca',
        '0xabcabcabcabcabcabcabcabcabcabcabcabcabca',
        '0xabcabcabcabcabcabcabcabcabcabcabcabcabca',
        '0xabcabcabcabcabcabcabcabcabcabcabcabcabca',
      ],
    },

threshold is 1, which means only one of the validator's signatures is required.

Woohoooo!!! You are done setting up the Hyperlane deployment on Polygon zkEVM testnet with remotes Mumbai and Sepolia.

5. Deploying Your Hyperlane

To deploy Hyperlane, run the following command on your terminal.

DEBUG=hyperlane* yarn ts-node scripts/deploy-hyperlane.ts --local polygonzkevmtestnet \
  --remotes mumbai sepolia \
  --key 0xbeda2b3910bae7dbfb4e65e9c0931f001066d4f0df257b77ad55093fa271bde2

In the above command,

we are running the deploy-hyperlane.ts script
with polygonzkevmtestnet as local chain and
mumbai and sepolia as remotes. Since mumbai and sepolia are already provided by the Hyperlane SDK we don't need to add the configurations again.
the value after key param is your private key to the address that contains funds for all the networks.

After running the command, wait for a few minutes till your terminal looks like this 👇🏻

Congrats!!! You just deployed Hyperlane on Polygon zkEVM Testnet.

To test this deployment, you must run validators and relayers for all the chains you deployed (local + remote). To learn how to set up validators and relayers, check out these guides on the Hyperlane blog 👇🏻

https://blog.hyperlaneindia.xyz/hyperlane-relayers-setup-guide

https://blog.hyperlaneindia.xyz/hyperlane-validators-setup-guide

Thanks for reading this article; I hope you learned something today.

💡

If you wanna explore more check out the Hyperlane Docs, and if you have any queries get them resolved in Hyperlane India Telegram Channel.

Let me know if you have any doubts on Twitter, Lenster or LinkedIn.

Happy Learning 🙌🏻

Keep Building 🧱🚀

Hyperlane from A to Z

2023-09-15T10:58:18.882Z

gm gm gm!!!

Even in a vast blockchain network with countless nodes and layers, users need help utilizing the decentralized network's complete potential because DApps use different chains. Some use Ethereum, some Polygon, some Gnosis, and so on!

In this environment, developers should build chain-agnostic applications—no dependency on one chain and no restriction for any user.

Now, solving this interoperability issue between different chains requires devs to build robust and, more importantly, secure designs, which is a highly technical and resourceful process, and to save devs from going through such pain Hyperlane comes into the picture.

This article will explain almost all about Hyperlane and how it works, so grab a coffee ☕️ and LFG 🚀

What is Hyperlane?

Hyperlane is a permissionless interoperability protocol that helps devs send arbitrary data across chains⛓

https://twitter.com/megabyte0x/status/1686628441888804864

Permissionless means no one requires any permission from the Hyperlane team to use Hyperlane SDK, contracts, or even while deploying on new chains as I did👇🏻

https://twitter.com/megabyte0x/status/1651938319570456577

Interoperability means sending between different chains. Imagine initiating a transaction on Ethereum to close a position on Polygon.

Hyperlane is a complete modular protocol that helps devs to customize it according to their application requirements.

The following are the key components of Hyperlane:

Mailbox
Interchain Security Module (ISM)
Interchain Gas Payment (IGP)
Agents

This article will explain each of them. You can either learn about them in depth one by one or go directly to the example.

What is a Hyperlane Mailbox?

Mailbox is an on-chain API to send and receive interchain messages.

https://twitter.com/megabyte0x/status/1686979539291762688

Mailbox is the middleman that helps devs connect different chains and leverage them to build something new.

Hyperlane deployed a Mailbox contract on each of its supported chains. The contract interface defines two functions that must be present in these cross-chain contracts, dispatch and process.

How Does the `dispatch` Function Work?

This function lets you send data from the origin to the destination chain.

It accepts several params:

_destinationDomain (uint32): The domain of the destination chain or the deployer.
_recipient Address (bytes32): The recipient's address.
_messageBody (bytes): The content of the message as raw bytes.

The function works by following these steps:

It checks whether the message length exceeds the 2KiB length.
It formats the _messageBody using Message.sol.
Message.sol provides an id function that returns a KECCAK256 hash of _message.
This hash becomes the _id and is saved into an incremental Merkle tree.
The function uses the Merkle tree to verify fraud proofs in Hyperlane's staking and slashing protocol.

How Does the `process` Function Work?

The function is called on the destination chain to receive the message. It accepts the following two params:

It works by following these steps:

The _message argument is the one the dispatch function formatted with Message.sol.
The _metadata argument is metadata provided by the ISM relayer to verify _message.
The function checks whether the _id is in the array of delivered messages. If it is, it reverts with delivered; if not, it adds it to that array.
The function gets the ISM address for the recepientAddress. If the recipient has defined a specific ISM, it uses that; otherwise, it uses the default ISM for the chain.
It uses the ISM address to verify messages received by the Mailbox.
After verification, it emits the message received event using the IMessageRecepient.sol

You can learn more about Mailbox in the Hyperlane docs..

What are Hyperlane Interchain Security Modules?

An ISM verifies that the messages delivered on the destination chain come from the origin chain.

https://twitter.com/megabyte0x/status/1687471625724383232

Mailbox uses the ISM to verify the message Mailbox received from a relayer before executing transactions.

Devs can define their own ISM for their application or can use default ISMs provided by the team, using the ISpecifiesInterchainSecurityModule.sol

ISM can be configured per the application requirements, with all the additional parameters required by the application.
Devs can use more than one ISM in their application to increase security and work according to the chain's consensus.
Devs can use IInterfaceSecurityModule.sol and build a custom ISM according to their needs.

Each ISM comes with two main functions:

How Does the `verify` Function Work?

This function takes two params:

message(bytes): Message that needs to be verified.
metadata(bytes): Off-chain bytes provided by the relayers.

How Does the `moduleType` Function Work?

This function signals relayers about the module type to include in the metadata.

How to Implement an Interchain Security Module?

You can use the ISpecifiesInterchainSecurityModule.sol module to implement a custom ISM for your application.

The team provides different prebuilt ISMs:

MultisigISM
RoutingISM
AggregationISM
OptimisticISM
WormholeISM
HookISM

You can find more details about ISMs in the Hyperlane docs.

What is the Hyperlane Interchain Gas Paymaster?

The IGP is an on-chain API to pay relayers that deliver the message on the destination chain.

https://twitter.com/megabyte0x/status/1687818750635261954

An interchain message requires two transactions: one on the origin chain to send the message and one on the destination chain to receive it.

When users send the message via a Mailbox contract on the origin chain to a relayer, they must include the gas fee to cover the gas fee on the destination chain. The IGP calculates the gas fee and sends the amount to the relayer.

IGP provides two functions:

payGasFor()
quoteGasPayment()

How does the `payForGas` Function Work?

This function takes four parameters:

_messageId
destinationDomain
gasAmount
refundAddress

When the user sends the above parameters, the following steps happen:

The function gets the gas fee required on the destination chain by calling quoteGasPayment(). It reverts if the required amount exceeds the msg.value.
It calculates the overpaid amount; if it exceeds 0, it sends the amount to the refundAddress.
It emits a GasPayment event.

How does the `quoteGasPayment` Function Work?

This function takes the following parameters: _destinationDomain and _gasAmount. It works like this:

The function gets the token exchange rate and the gas price for the destination chain.
It calculates the gas fee on the destination chain.
It calculates the number of native tokens required on the origin chain and returns it.

The IGP Workflow

Let's look at a complete workflow of IGP on the origin chain to deliver the message on the destination chain:

The Hyperlane docs have additional details if you want to learn more about IGP.

What are Hyperlane Agents?

Agents are the off-chain actors that power Hyperlane.

https://twitter.com/megabyte0x/status/1688514083287678977

There are three agents in the Hyperlane protocol: Validators, relayers, and watchtowers.

Since Hyperlane is a permissionless interoperability protocol, you can take the role of any agent and contribute to the network's security.

What are Hyperlane Validators?

They sign the current Merkle root, which they receive from the Mailbox.latestCheckpoint().

Validators are supposed to sign the checkpoint after it reaches the finality to maintain the network's security.

After signing the checkpoint, validators post signatures on the available storage so that the Relayers can aggregate them.

What are Hyperlane Relayers?

Relayers are responsible for delivering messages to the recipient.

It works as follows:

Observe Mailbox for new messages.
Use Mailbox to get the ISM implemented by the recipient.
Aggregate the metadata for the ISM.
Deliver the message.

Relayers can also have configurations for the messages they want to deliver:

A sender/recipient allowlist.
A sender/recipient denylist
Getting paid on-chain after delivering.

The relayers get rewarded when they process the message with the gas fee.

What are Hyperlane Watchtowers?

They are the police of the Hyperlane protocol. They look for fraudulent validators in the network and slash their stake. Watchtowers get rewarded when they submit the correct report of fraud.

You can learn more about agents in the Hyperlane docs.

Example: How to Send a Message from Polygon zkEVM to Ethereum?

Let's use an example to understand how Hyperlane's components work together.

Jim wants to send a message data to Dwight from Polygon zkEVM to Ethereum with Hyperlane.

https://twitter.com/megabyte0x/status/1688875226745253888?s=20

The following steps are required to transfer the message:

Jim sends the message data, recipient address, and destination chain to the Maibox contract on the Polygon zkEVM chain.
The Mailbox emits an event that gets indexed.
Validators sign the latest checkpoint.
The signature gets stored in the database.
Jim pays the gas fee using IGP during the process.
When the relayer receives the gas fee, it relays the message and metadata on the Ethereum chain.
The messageBody is sent to the ISM for verification.
The message gets delivered to Dwight on the Ethereum chain.

Whoo!!🤩 This was quite a lot of workflow and solidity contracts understanding.

💡

If you wanna explore more check out the Hyperlane Docs, and if you have any queries get them resolved in Hyperlane India Telegram Channel.

You can connect with me on Twitter, Lenster or LinkedIn.

Happy Learning 🙌🏻

Keep Building 🧱🚀

Build Your Own NFT Collection with QuickNode and Optimism

2023-09-04T12:34:58.700Z

Building and deploying your own NFT collection can be time and money-consuming, especially with the gas prices on Ethereum. With the rise of layer-2 solutions and cheap RPCs, this doesn't have to be the case! This tutorial will explain building an NFT Collection using the ERC-721 token standard. You will store all NFT assets and metadata on IPFS with QuickNode and deploy the smart contract on Optimism Goerli Testnet.

Requirements

A basic understanding of Solidity development will be helpful but is not required.
A basic understanding of the ERC-721 token standard will be helpful but is not required.
A basic understanding of the Remix IDE will be helpful but is not required.
Image assets and metadata of the NFT collections.
MetaMask or any other wallet and a small amount of Goerli test ETH.
A free QuickNode account.

What is QuickNode IPFS?

The QuickNode IPFS service lets you store data decentralized using IPFS. Your files are automatically spread and replicated across global data centers, ensuring redundancy and distribution throughout the network.

What is Optimism?

Optimism is a layer-2 scaling solution that Ethereum developers choose for its speed and low transaction costs while maintaining full compatibility with the EVM.

What are the Steps?

Store NFT assets and metadata on QuickNode IPFS.
Create and deploy an ERC-721 contract on the Optimism Goerli Testnet.
Interact with the Smart Contract to mint NFTs
View your NFTs on OpenSea.

Storing Files on IPFS

First, you upload your images and metadata via QuickNode.

Open the QuickNode website and navigate to the "Storage" section. Click the Add a file button and select the file from your local machine.

After you upload the file, it will appear like this, showing the file name, CID, status, and other information about the file.

Upload images for each of the NFTs. You'll find all the images on GitHub. The outcome will look similar to this.

Create three JSON metadata files to store information about our NFT collections.

0.json: Agra collection
1.json: Delhi collection
2.json: Goa collection

The 0.json file should look something like this:

{
  "name": "Agra",
  "description": "Agra is a historic city in northern India, renowned for the iconic Taj Mahal, a marble mausoleum. It's a UNESCO World Heritage site and symbolizes love and architectural splendor. Agra also boasts Agra Fort and Fatehpur Sikri, both reflecting the city's Mughal heritage and attracting countless tourists for their cultural significance.",
  "image": "ipfs://Qmdr1zPumimEFKRkszo3nfFhGQ3UwofQXMbfDy1wd1gdLQ",
  "properties": {
    "rarity": "a bit rare",
    "fanciness": 8
  }
}

name: Contains the name of the NFT.
description: Contains the description of the NFT.
image: Includes the link to the previously obtained image (IPFS URL).
properties: Encompasses the various attributes of the NFT.

Create the remaining JSON files, 1.json and 2.json, for the Delhi and Goa collections. You'll find the Metadata example on GitHub.

Similarly, upload your metadata folder to QuickNode IPFS. Once successfully uploaded, it will appear as shown:

You can view the JSON file by clicking on the filename in the QuickNode IPFS dashboard.

Now, click "COPY IPFS URL" to copy the CID and the gateway link, allowing you to access the file. For example, this is the link to the 0.json file.

https://quicknode.quicknode-ipfs.com/ipfs/QmQQEjRjhUQPgJ51U2PKkwyRLgktzGWmX95vgUzWfBj5gb

Creating & Deploying the NFT Smart Contract

Use the OpenZeppelin contracts library to create an ERC-721 contract and deploy it on the Optimism Goerli Testnet using the Remix IDE. Ensure you have some Goerli Ether, which you can get from the Quicknode Optimism Faucet.

Create a new file named QuickNft.sol in Remix IDE and paste the following code:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.17;

import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/Strings.sol";

error NFT_NOT_EXIST();
error YOU_ALREADY_MINTED_NFT();
error ALL_NFTS_ARE_MINTED();

contract QuickNft is ERC721Enumerable, Ownable {
    uint256 public supplies = 500;
    uint256 public minted;
    string[] public cid = [
        "ipfs://QmQQEjRjhUQPgJ51U2PKkwyRLgktzGWmX95vgUzWfBj5gb",
        "ipfs://Qmch5VaqXCc5ZbwKuL2awac1vrBXBBPiB5h7WxtYKDZ7DS",
        "ipfs://QmQg5wf1KHLDA1pEg51wK44UqPa6wJztTxppgb92VyPEbR"
    ];

    constructor() ERC721("QuickNft", "QNN") {}

    /**
     * @notice function to put NFT on Opensea
     * @param _cidId ID of the metadata of NFT we want to mint
     * @dev tokenURI overrides the Openzeppelin's ERC721 implementation for tokenURI function
     * This function returns the URI from where we can extract the metadata for a given tokenId
     */
    function tokenURI(
        uint256 _cidId
    ) public view virtual override returns (string memory) {
        if (_cidId >= cid.length) revert NFT_NOT_EXIST();
        return string(abi.encodePacked(cid[_cidId]));
    }

    /**
     * @notice function to mint the NFT
     * @param _cidId CID ID to select the metadata of your choice
     */
    function mint(uint256 _cidId) public {
        if (_cidId >= cid.length) revert NFT_NOT_EXIST();
        if (minted + 1 > supplies) revert ALL_NFTS_ARE_MINTED();
        _safeMint(msg.sender, minted);
        unchecked {
            ++minted;
        }
    }

    /**
     * @notice function to get total number of NFTs minted
     */
    function totalNftMinted() public view returns (uint256) {
        return minted;
    }
}

Let's break down the above Solidity smart contract code line by line:

// SPDX-License-Identifier: MIT

This line specifies the license identifier for the contract. In this case, it's indicating that the contract is under the MIT License.

pragma solidity 0.8.17;

This pragma sets the version of Solidity. In this case, the compiler will use version 0.8.17 of Solidity for the compilation.

import "@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/Strings.sol";

These lines are importing necessary contracts from the OpenZeppelin library. The the ERC721Enumerable contract helps to create an ERC-721 token that supports enumeration (listing tokens), the Ownable contract will provide basic ownership functionality and the Strings contract is used for manipulating strings.

error NFT_NOT_EXIST();
error YOU_ALREADY_MINTED_NFT();
error ALL_NFTS_ARE_MINTED();

These lines define custom error messages that we used in the contract.

contract QuickNft is ERC721Enumerable, Ownable {

This line defines the QuickNft contract, which inherits from ERC721Enumerable and Ownable, so the contract will be both an ERC-721 token (with enumeration capabilities) and have ownership functionality.

uint256 public supply = 500;
uint256 public minted;

These lines declare two state variables. supply represents the total number of NFTs available for minting, and minted keeps track of how many NFTs people minted so far.

string[] public cid = [
    "ipfs://QmQQEjRjhUQPgJ51U2PKkwyRLgktzGWmX95vgUzWfBj5gb",
    "ipfs://Qmch5VaqXCc5ZbwKuL2awac1vrBXBBPiB5h7WxtYKDZ7DS",
    "ipfs://QmQg5wf1KHLDA1pEg51wK44UqPa6wJztTxppgb92VyPEbR"
];

An array cid is defined, containing three IPFS URLs that represent the metadata of the NFTs.

constructor() ERC721("QuickNft", "QNN") {}

The contract's constructor initializes the ERC-721 token with "QuickNft" as the name and "QNN" as the symbol.

function tokenURI(uint256 _cidId) public view virtual override returns (string memory) {
    if (_cidId >= cid.length) revert NFT_NOT_EXIST();
    return string(abi.encodePacked(cid[_cidId]));
}

This function, tokenURI, overrides the default ERC721 behavior and returns the IPFS URL (metadata URI) associated with the given _cidId.

function mint(uint256 _cidId) public {
    if (_cidId >= cid.length) revert NFT_NOT_EXIST();
    if (minted + 1 > supplies) revert ALL_NFTS_ARE_MINTED();
    _safeMint(msg.sender, minted);
    unchecked {
        ++minted;
    }
}

The mint function allows users to mint NFTs. It checks if the _cidId is valid and the total number of minted NFTs is within the available supply. If this is the case, it mints a new NFT for the caller and increments the minted count.

function totalNftMinted() public view returns (uint256) {
    return minted;
}

The totalNftMinted function returns the total count of minted NFTs.

In case you don't have the Optimism Goerli Testnet set up in your wallet, follow these steps:

Creating an Optimism Endpoint on QuickNode

To deploy a smart contract to Optimism's test blockchain, Goerli, you'll need an API endpoint to communicate with the network. Go to the QuickNode Dashboard to configure it.

Once logged in, click the "Create an endpoint" button, then select the "Optimism" chain and "Goerli" network.

After creating your endpoint, copy the HTTP provider link and keep it handy, as you'll need it next.

Configuring Your Web3 Wallet with QuickNode

Configure your RPC settings if you're using MetaMask to deploy this contract. Some compatible wallets are Coinbase Wallet, Rainbow Wallet and TrustWallet.

Open up MetaMask and click the network dropdown at the top. After, click the "Add Network" button.

At the bottom of the page, click "Add a network manually" and fill out the following details:

Network name: Optimism Goerli Testnet
New RPC URL: Enter the QuickNode HTTP URL you retrieved earlier
Chain ID: 420
Currency symbol: ETH
Block Explorer URL: https://optimism-goerli.blockscout.com

It should end up looking similar to this:

Compiling the Smart Contract

Open Remix IDE, copy and paste the above code, and navigate to the Deploy section. Select 'Injected Web3' as the environment, and deploy it by choosing the correct contract name. You need to select the chain on your MetaMask wallet. In our case, we are deploying it on the Optimism Goerli Testnet with chain ID 420. Click the Deploy button

Approve the transaction on MetaMask by clicking the Confirm button. Once the transaction is complete, your contract will be deployed.

Now you can perform functions like mint NFT by entering CID ID. We can also retrieve the NFT URI by entering the CID ID.

Minting an NFT

Enter the CID ID of the NFT you want to mint and click on the Confirm Button.

After some time, you can see the NFT on OpenSea.

🎉BOOM 🎉

You've completed the entire tutorial. Give yourself a well-deserved pat on the back. You've learned how to:

Create an NFT Collection using the ERC-721 Token standard.
Store NFT Metadata in a decentralized manner using QuickNode IPFS.
Compile and deploy a Smart Contract on the Optimism Goerli Testnet.
Interact with the smart contract using Remix.

🎉 Bonus for sticking till the end: use code BUILD-AMB-15. This coupon gives you 1 month of the QuickNode Build ($49) plan for free 🎉

###💥 Simply WOW 💥

If you found this tutorial helpful and enjoyable, consider sharing it with your friends. I hope you've gained new insights or even solved a challenge. Thank you for reading, and have a great time!

Feel free to connect with me on Twitter, GitHub, and LinkedIn. I welcome your suggestions and comments!

WAGMI 🚀🚀

Site Name Blog

x402 Deep Dive: A Payment Standard for the Internet

How Does x402 Work?

The Seller

The Buyer

The Facilitator

How to Use x402 in Your Apps?

Using x402 as Seller

Using x402 as Buyer

Conclusion

Using Arweave for AI Provenance

What's Real?

Proof of Origin

Arweave and HyperBEAM

How Could it Work?

What are the Use Cases?

Why Does This Matter Now?

The Bottom Line

An Introduction to Force Inclusion

What is Censorship Resistance?

What is Force Inclusion?

How is Force Inclusion Possible?

Trying Out Force Inclusion

Conclusion

An Introduction to Blockchain RPC Nodes

What is an RPC Node?

How do RPC Nodes Work?

Reading Data From a Blockchain

Writing Data to a Blockchain

Subscribing to Events of a Blockchain

How to Use an RPC Node?

Hosting Your Own RPC Node

Using a Public RPC Node

Using an RPC Node Provider

Conclusion

Working With Solana Tokens Using Native Rust

How do Solana Tokens Work?

Setting Up a Development Environment

Creating and Initializing a Token Mint

Creating the Token Mint

Initializing Token Mints

Creating an Associated Token Account

Burning Tokens

Conclusion

BuildBear Tutorial: Cross-Chain Bridge

Sign in to the BuildBear Dashboard

Create a Sandbox

Create Your BuildBear Sandbox

Forking Options

Advanced Options

Your RPC Is Ready for Use

Faucet

Get ERC20 Tokens

Add ERC-20 Tokens

Get Native Tokens

Add Native Tokens or ERC-20 Tokens

Plugins Installation

Contracts Verification API

Supported Verification Types

BuildBear Explorer

Key Features

Monitoring Transactions on BuildBear Explorer

Transaction Debugging

Building a Cross-Chain Bridge with Node Relayer on BuildBear

What We Will Learn

Project Repository

How it Works

Directory and Project Structure

Create Sandboxes and Install Plugins

Environment Variables & Wallet Setup

foundry.toml

Funding your Deployer & Receiver Wallet

Creating Contracts & Scripts

Bridge.sol Contract

Foundry Scripts & Their Usage

HelperConfig.s.sol

DeployBridge.s.sol

InteractBridge.s.sol

How do these scripts work together?

Relayer

`foundry.toml`

`Bridge.sol` Contract

`HelperConfig.s.sol`

`DeployBridge.s.sol`

`InteractBridge.s.sol`

Sending tokens to the `TokenGateCommunity` Contract

Withdrawing tokens from the `TokenGateCommunity` Contract

Setting the `entryTokenAmount` value