OnThru

One signed guestbook post. Two deployed programs. One real CPI path.

OnThru is a proof-first reference dApp for Thru alphanet. It shows how a wallet-signed message can move through a Guestbook program, invoke a separate Reputation program, and leave readable on-chain state and events behind.

GitHub · X · Thru documentation · Explorer

Project Status

OnThru has passed the core Thru implementation path on alphanet.

Area	Status
Guestbook C program	Built and deployed
Reputation C program	Built and deployed
ABI analyze, codegen, and reflect	Passed for both programs
ABI publication	Published on-chain
Guestbook to Reputation CPI	Live-verified
Frontend routes	Landing, app, and debug implemented
Light and dark themes	Implemented
Hosted-wallet browser transaction	Wiring implemented; manual approval still pending
Public frontend deployment	Not completed yet

The current release is honest about its boundary: the programs, ABIs, live CPI, and frontend build are validated; a browser-approved wallet transaction and public frontend hosting still need final QA.

What OnThru Demonstrates

OnThru is intentionally small, but it covers the important parts of a real Thru application:

• C programs with explicit account ownership and authorization.
• ABI authoring, analyze, code generation, fixture creation, and reflect validation.
• A genuine cross-program invocation from Guestbook into Reputation.
• A deployed program relationship where Reputation accepts updates only from Guestbook.
• A Next.js application using the Thru web SDK and hosted wallet integration.
• State-proof-backed account derivation for a program-owned message account.
• Explorer-readable account state, transaction status, and emitted events.
• A debug surface that explains what happened on-chain instead of showing mock data.

The frontend never performs a second direct Reputation write to imitate CPI. The reputation update is produced by the Guestbook program during the same transaction.

The Core Transaction

Wallet
  |
  | signs one guestbook.post_message instruction
  v
Guestbook Program
  |
  | creates or updates the Guestbook-owned MessageAccount
  | invokes Reputation through authorized CPI
  v
Reputation Program
  |
  | verifies the immediate caller is the configured Guestbook program
  | updates the author's ProfileAccount
  v
Confirmed state and events

A successful post follows this order:

1. The user prepares a short message and connects a Thru wallet.
2. The frontend derives the program-owned MessageAccount and creates the required state proof.
3. The wallet signs one Guestbook instruction.
4. Guestbook validates the author, stores the message, and invokes Reputation through CPI.
5. Reputation checks the configured caller and updates the author's profile.
6. Guestbook and Reputation emit events.
7. The app and debug route reconcile the confirmed transaction and account state.

Program Responsibilities

Guestbook

Guestbook owns message data and the user-facing write instruction.

It is responsible for:

• Initializing the Guestbook root account.
• Validating the message author and signer.
• Creating and storing MessageAccount data.
• Keeping a message count.
• Calling Reputation through CPI.
• Emitting the MessagePosted event.

The live Guestbook program account is:

ta6OGdoFUkNhbRYd_17veA7oKW_emVrxIfnELrlK616I3M

Reputation

Reputation owns profile state and the authorization boundary.

It is responsible for:

• Initializing author profiles.
• Tracking post count and reputation score.
• Accepting record_guestbook_post only from the configured Guestbook caller.
• Rejecting unauthorized direct reputation mutations.
• Emitting the ReputationUpdated event.

The live Reputation program account is:

tasOpbHKcSrN3Hce-Bp69pj9g8r7Xqlqt8wWZ7WE94wHRd

Account Model

Account	Owner	Purpose
GuestbookAccount	Guestbook	Root configuration, message count, and Reputation program reference
MessageAccount	Guestbook	Author, message index, message hash, timestamp, and status
ReputationConfigAccount	Reputation	Authorized Guestbook caller and program configuration
ProfileAccount	Reputation	Author, post count, reputation score, and last update time

The important ownership rule is that each program mutates its own state. Guestbook does not write Reputation's profile directly; it invokes Reputation and lets Reputation enforce its own contract.

Live Deployment Snapshot

The default target network is Thru alphanet.

Resource	Address or value
RPC	https://rpc.alphanet.thru.org
Network	alphanet
Guestbook program	ta6OGdoFUkNhbRYd_17veA7oKW_emVrxIfnELrlK616I3M
Guestbook config account	taQTQFjyqvIxu8GuZm7YR2UaXZpo-eDe-QsGssmDl9CYh9
Guestbook published ABI	ta2XXlvJBhG5uUyu7w3OylWxZO1kKdwPmQ8FPpmLZe2Pqm
Reputation program	tasOpbHKcSrN3Hce-Bp69pj9g8r7Xqlqt8wWZ7WE94wHRd
Reputation config account	taZL0vnyFlJiCH2S3bKRv5ZH3T9DhqbZDicHDsfjHSsb5F
Reputation published ABI	tax3XKSAVZnCWLzSQDTyF-g1oYUXtLmT42umhA_S-4tjYl

The latest verified end-to-end transaction is:

ts3WcweoChxJJoy6I_Ekoz82x1ll57lMaq28YljOhQtwKSYT21z8wNPz2rghGOqsc_Nyi6K7YitsBBfSimXEMbAx3y

Observed result:

• Slot: 27082
• Guestbook message count: 2
• Author profile post count: 2
• Reputation score: 20
• Events emitted: 2
• Compute units: 29,424
• VM error: none
• User error: none

Repository Layout

.
├── apps/
│   └── web/                 Next.js landing page, app, and debug routes
├── docs/                    Architecture, deployment, and validation notes
├── packages/
│   ├── abi/                 Shared ABI-facing TypeScript wrappers
│   └── shared/              Shared constants and application types
├── programs/
│   ├── guestbook/           Guestbook C source, ABI, fixtures, and build files
│   └── reputation/          Reputation C source, ABI, fixtures, and build files
├── scripts/                 Build, ABI, deploy, publish, and live-test scripts
├── .env.example             Public configuration template
├── package.json             Workspace scripts
└── package-lock.json        Reproducible JavaScript dependency versions

Local-only continuity notes, agent tooling, generated build output, and the diagnostic CPI probe are intentionally excluded from the public repository.

Prerequisites

You need:

• Node.js and npm.
• Windows PowerShell for the repository scripts.
• WSL Ubuntu.
• Thru CLI 0.2.38 or a compatible installed version.
• The Thru C SDK and RISC-V toolchain available inside WSL.
• A funded Thru identity only for live deployment or live write tests.

On PowerShell, use thru.cmd instead of thru if the execution policy blocks the PowerShell shim.

The program build scripts expect the WSL toolchain root:

RISCV_TOOLCHAIN_ROOT=/home/bebekgoyang/.thru/sdk/toolchain

Local Setup

Install the workspace dependencies from the repository root:

npm.cmd install

Create local environment files from the template and fill the public program and account values for your target network:

Copy-Item .env.example .env.local
Copy-Item .env.example apps/web/.env.local

Do not place private keys in either frontend environment file. Values prefixed with NEXT_PUBLIC_ are available to the browser and must be treated as public.

The important frontend variables are:

NEXT_PUBLIC_THRU_RPC_URL
NEXT_PUBLIC_THRU_NETWORK
NEXT_PUBLIC_THRU_GUESTBOOK_PROGRAM_ID
NEXT_PUBLIC_THRU_REPUTATION_PROGRAM_ID
NEXT_PUBLIC_THRU_GUESTBOOK_ACCOUNT
NEXT_PUBLIC_THRU_REPUTATION_CONFIG_ACCOUNT
NEXT_PUBLIC_THRU_WALLET_IFRAME_URL

For the hosted wallet, use a trusted SDK origin such as:

https://app.tid.sh/embedded

Build and Validation

Run the complete local validation sequence from the repository root:

npm.cmd run programs:build
npm.cmd run abi:validate
npm.cmd run lint
npm.cmd run build

The commands cover:

1. Building both C programs through WSL.
2. Running ABI analyze, TypeScript codegen, and reflect validation.
3. Linting the Next.js frontend.
4. Creating a production Next.js build.

To run the frontend locally:

npm.cmd run dev

Then open:

http://localhost:3000

The current local handoff server has also been verified on port 3004 when port 3000 is occupied.

Web Routes

Route	Purpose
/	Product landing page with the live CPI explanation
/app	Guestbook composer, wallet connection, transaction state, feed, and reputation panel
/debug	Read-only program, account, and latest transaction inspection

The debug route is designed to work without a wallet connection for read-only verification.

Deployment Workflow

Program deployment must follow the dependency order:

1. Build and validate the Reputation program and ABI.
2. Deploy Reputation.
3. Initialize Reputation with the Guestbook program ID as its authorized caller.
4. Build and validate Guestbook.
5. Deploy Guestbook.
6. Initialize Guestbook with the Reputation program and configuration accounts.
7. Publish both ABIs.
8. Update the public frontend configuration.
9. Run a live post and verify state, CPI, and events.

Relevant scripts:

powershell.exe -ExecutionPolicy Bypass -File scripts/build-programs.ps1
powershell.exe -ExecutionPolicy Bypass -File scripts/validate-abi.ps1
powershell.exe -ExecutionPolicy Bypass -File scripts/deploy-reputation.ps1
powershell.exe -ExecutionPolicy Bypass -File scripts/deploy-guestbook.ps1
powershell.exe -ExecutionPolicy Bypass -File scripts/publish-abi.ps1
powershell.exe -ExecutionPolicy Bypass -File scripts/live-post-message.ps1

Do not treat a successful local build as a live deployment. Always check RPC readiness, the active identity, funding, program status, ABI publication, and a confirmed transaction.

Frontend Design Principles

OnThru keeps the primary experience focused:

• One obvious write action: post a short guestbook message.
• One real transaction path: Wallet to Guestbook to Reputation.
• No mock transaction feed presented as chain truth.
• Technical evidence lives in the debug route.
• Light and dark themes preserve the same hierarchy.
• Motion explains execution state and respects reduced-motion preferences.
• Account and transaction values are shown only when they are live, decoded, or explicitly labeled as local session state.

Security and Repository Scope

Never commit:

• .env.local or any private key.
• Wallet secrets, seed phrases, or browser storage exports.
• node_modules, build output, or local logs.
• MEMORY.md, TASK.md, or SOUL.md.
• Agent scaffolding, skill lock files, or local temporary directories.
• The diagnostic CPI probe, which was used for local runtime investigation and is not part of the product path.

Before the first GitHub push, review the staged file list and confirm it contains only product source, reproducible build/validation scripts, public docs, and required dependency manifests.

Known Limitations

• Hosted-wallet passkey creation and a browser-approved post_message transaction still need manual QA.
• Automated screenshot QA is unavailable in the current environment; route HTTP, served CSS, lint, and production build checks have passed.
• Public frontend hosting and production domain configuration are not completed yet.
• The current target is alphanet, not a production mainnet deployment.
• The npm registry currently reports two moderate PostCSS-via-Next advisories with no high or critical findings; dependency remediation should be reviewed before a public launch.

Documentation

• Architecture: docs/architecture.md
• Deployment: docs/deployment.md
• Validation: docs/validation.md
• Thru documentation: https://thru.org/docs
• Thru web SDK: https://thru.org/docs/sdks/web
• Thru wallet overview: https://thru.org/docs/wallet/overview
• Thru ABI overview: https://thru.org/docs/abi/overview
• Thru Explorer: https://scan.thru.org

Project Links

• Repository: https://github.com/Alice699/onthru
• X: https://x.com/0xLuxee

License

No license file has been added yet. Add an explicit license before accepting external contributions.