Skip to content
JournalTORIS / FIELD NOTES

← Blog Project notes

[Case Study] PEPEBear: On-Chain and Off-Chain Design of a Solana-Based Community Platform

A technical case study of PEPEBear, a community platform Toris built on Solana, covering wallet UX, on-chain and off-chain data separation, and the community validation loop.

9 min read Read the Korean original

Joohwan Yu · Founder, Full Stack Developer

Toris · Published

Contents

Q. How did you decide what to put on-chain in a gamified community? The test was “if this is manipulated, do other users lose out?” Only the core state that needs verification went on-chain, while balance values and UI state stayed off-chain.

Product name: PEPEBear Development period: November 2025 Tech stack: Next.js, TypeScript, React, Solana (@solana/web3.js, Wallet Adapter), Anchor Framework Positioning: A community participation platform that layers gamification on top of the Solana blockchain

PEPEBear is a Web3 community platform that Toris designed and built in the Solana ecosystem. It organizes a token community’s participation into a gamification structure of points, levels, and achievements, and visualizes on-chain data in near real time. This post records the architecture decisions made within a short one-month development cycle, especially the separation of on-chain and off-chain data and the community-driven balance tuning.

Summary of Key Decisions

DecisionChoiceTrade-off
Chain and contract layerSolana + Anchor FrameworkAccepted ecosystem lock-in in exchange for low fees, fast finality, and less boilerplate
Data storageOn-chain/off-chain split by required trust levelGave up full on-chain transparency to secure fees and UX
Anti-manipulation checksImplemented in the smart contract, not the clientThe burden of irreversible deployment, with the trust boundary moved outside the client
On-chain readsPeriodic polling + caching (WebSocket rejected)Gave up second-level real-time updates for stability within public RPC limits
Balance valuesManaged as off-chain dataExcluded from on-chain verification, enabling frequent tuning loops

1. Problem Definition and Product Hypothesis

A chronic problem for token communities is the lack of a participation structure. Most member activity evaporates inside chat rooms, and contributions are neither recorded nor tied to a reward structure. On-chain data such as holder status is public, but it has not been processed into a form the community can look at together.

From here I formed a product hypothesis.

“If you structure community activity into points, levels, and achievements and show on-chain data transparently, one-time visitors turn into ongoing participants.”

The target is members of Solana-based token communities. One design principle was made clear from the start: the value of this platform lies not in the price of an asset but in the record of participation and the transparency of data. So every screen and mechanism in the product focused on community activity and the visualization of on-chain facts, and any other narrative was excluded.

Advertisement

2. Constraints

  • One-month development period: I had to deliver a working product within November 2025. Every architecture choice was under this time constraint.
  • Cost pass-through structure of transactions: In Web3, the cost of changing state (fees) is paid by the user. The decision to put one feature on-chain is the decision to bill users for it.
  • Irreversibility of smart contracts: A deployed contract is hard to modify. The “deploy first and fix later” approach of web services does not work.
  • RPC infrastructure limits: Without our own validator node, I had to depend on public RPC endpoints, and free endpoints have request limits.
  • Assuming an adversarial environment: A system with points and rankings at stake must be designed on the assumption that people will try to manipulate it.

3. Technical Design and Trade-offs

3.1 Stack Choice: Solana + Anchor + Next.js

I chose Solana for the chain, for two reasons. Transaction finality is fast and fees are low. In a high-interaction product like gamification, per-transaction cost and wait time directly determine UX. For the contract layer I used the Anchor Framework. Compared with writing raw Solana programs, it reduces the boilerplate of account validation and serialization, so in a one-month schedule I could focus on the substance of the verification logic.

The frontend is Next.js + TypeScript. A big factor was that @solana/wallet-adapter-react integrates well with the React ecosystem, letting me support multiple wallets such as Phantom and Solflare through a standardized interface.

3.2 On-Chain/Off-Chain Data Separation: The Core Decision of This Project

The most important architecture decision was what to put on the chain and what not to.

A design that keeps all state on-chain is theoretically the most transparent, but I rejected it for two reasons. First, if every point accrual becomes a transaction, users would pay a fee each time they act. Second, the wait for transaction finality would intrude on every interaction and wreck the UX. Conversely, keeping everything off-chain is fast and cheap, but it removes the reason a blockchain exists: tamper resistance.

The conclusion was a split based on the required trust level.

DataWhere storedRationale
Core state that needs verificationOn-chain (smart contract)Tamper resistance is the source of the value
Ancillary activity data, UI stateOff-chainCost and speed first, low incentive to manipulate

The criterion is simple. “If this data is manipulated, do other users lose out?” If so, verify it on-chain; if not, keep it off-chain. I implemented the anti-manipulation verification logic in the smart contract, not the client. Client code can be opened by anyone, so the trust boundary must sit inside the contract.

3.3 Wallet Integration: Not Making Web3’s First Gate a Drop-Off Point

Onboarding in a Web3 product starts with connecting a wallet, and a good share of drop-off happens right here. If the connection process is complicated or failures are unfriendly, users do not come back.

import { useWallet } from '@solana/wallet-adapter-react';

const { publicKey, connect, disconnect } = useWallet();

const handleConnect = async () => {
  try {
    await connect();
    // Connected: get the address via publicKey?.toBase58()
  } catch (error) {
    // Distinguish user rejection, network errors, etc. and show guidance
  }
};

I handled multiple wallets (Phantom, Solflare) through a single interface with Wallet Adapter, but put the weight of the design on the error paths. A wallet connection failure is not a single case. A user rejecting the approval window, a network error, and a missing wallet each require different guidance. Distinguishing failure reasons and showing them in the user’s language took as much code as implementing the success path.

3.4 On-Chain Data Tracking and RPC Strategy

To show holder rankings and balances, I query on-chain data through Solana RPC.

import { Connection, PublicKey } from '@solana/web3.js';

const connection = new Connection('https://api.mainnet-beta.solana.com');

const getTokenBalance = async (walletAddress: string) => {
  const publicKey = new PublicKey(walletAddress);
  const balance = await connection.getTokenAccountBalance(publicKey);
  return balance.value.uiAmount;
};

The trade-off here is real-time freshness versus RPC cost. After comparing WebSocket subscriptions and polling, I designed screens like rankings, where second-level precision is not essential, with periodic polling + caching. Running stably within the public RPC’s request limits took priority over ultra-real-time updates. Caching also absorbs duplicate queries for the same data, saving the RPC budget.

I visualized ranking changes with animation. I judged that making the moment a rank changes visible raises the value of staying on the community screen. Animation carries rendering cost, though, so I optimized it to trigger animation only for items where a change was detected.

3.5 Transaction Pipeline: Designing Failure as a Normal Path

On a blockchain, transaction failure is routine, not an exception. Network congestion, delays, even the user refusing to sign: I designed the transaction pipeline to treat failure as one of the normal states.

  • State tracking: Track transaction state from submission to finality and show the user the current stage. The goal is to eliminate the stretch where “I pressed the button and nothing happened.”
  • Retry logic: Failures from transient network problems are absorbed by automatic retries.
  • Error translation: Translate the raw errors returned by RPC into messages the user can act on.

On security, I made transparency of signing requests a principle. The moment a user signs a transaction is the most sensitive moment of trust in Web3. I gave clear information about what they were signing and created no unnecessary signing requests. The contract went through ample verification on testnet before mainnet deployment. In front of an irreversible deployment, testing is not a cost but insurance.

4. Validation and Coordination with the Community

What is special about Web3 products is that the users are the community. PEPEBear’s gamification design was not finished at a desk but tuned through repeated loops with the community.

4.1 Game Balance: The Designer’s Hypothesis and the Participants’ Reality

Balance values such as point accrual amounts, level tiers, and achievement conditions are at first only the designer’s hypothesis. Running actual user tests exposed the gap between hypothesis and reality: progress getting boring in certain stretches, or rewards for certain activities feeling too generous or too stingy. These do not show up in logs alone and can be confirmed only through participant feedback.

I ran a loop that tuned balance based on user test results. The principle I took from this: treat gamification numbers as data, not code. Assuming adjustments will be frequent, it is right to keep balance values in a structure that is easy to change. And this ties in with the on-chain/off-chain separation decision. Had I carved the balance logic, which needs frequent tuning, into an irreversible contract, the tuning loop itself would have been impossible.

4.2 Coordinating on the Assumption of Manipulation Attempts

In a system with rankings and points at stake, some users will always look for shortcuts. This is not something to blame but an input to reflect in the design. Auditing paths that could be manipulated from the client and moving the core verification into the smart contract was the result of observing “how the community uses (and misuses) the system.”

4.3 Trust Comes from Transparency

In a community platform, a ranking’s authority comes from the source of its data. I built the holder ranking to read directly from on-chain data rather than values entered by the operator, to give the community the trust of “a leaderboard even the operator cannot manipulate.” Web3 communities are sensitive to verifiability, and a data pipeline that matches that sensibility becomes the product’s trust asset.

5. Operations and Results

PEPEBear is deployed on Vercel and running (pepe-bear.vercel.app). Within the one-month development cycle, I completed and shipped the platform’s core loop: wallet integration, the gamification system (points, levels, achievements), real-time on-chain data tracking, smart contract integration, and an animation-based holder ranking.

The remaining work is also clear.

  • Contract optimization: The current contract still has room for compute optimization. Cutting unnecessary computation to lower the fee burden is the next step.
  • Onboarding UX: There is still a user base for whom the very concept of a wallet is a barrier to entry. Reducing Web3-specific friction further is the challenge.
  • Community feature expansion: Features that thicken the participation loop, while keeping the criterion for what counts as an on-chain verification target.

6. Reusable Lessons

  1. Decide where to store data by required trust level. “If it is manipulated, do others lose out?” is the criterion for the on-chain/off-chain split. All on-chain collapses under cost, and all off-chain collapses under trust.
  2. Do not put frequently changing logic in an irreversible place. Balance values go off-chain on the assumption of tuning loops, and verification rules go in the contract.
  3. Design failure as a normal path. Transaction state tracking, retries, and error translation are not extras but the body of Web3 UX.
  4. Put the trust boundary outside the client. Do not put verification where users can read and tamper with the code.
  5. The community is both a QA organization and a design partner. The balance gaps, the manipulation paths, and the standard of trust all came from observing the community. It is worth formalizing the feedback loop as part of the product development process.

Advertisement