---

Gluon Protocol — Dual-Token Mechanics (Solana)

Gluon is a Stability Nexus research initiative delivering a two-token stable-asset system on Solana.

• Stable token (neutron): targets peg reliability for on-chain commerce.
• Leveraged token (proton): captures reserve surplus and price reflexivity.

The system uses Anchor smart contracts, Pyth oracles, and Solana’s high-throughput runtime to coordinate fission, fusion, and transmutation in real time.

📄 Whitepaper: Gluon.

---

Table of Contents

• Overview
• Architecture
• Repository Layout
• Prerequisites
• Configuration
• Quick Start (Frontend)
• Anchor Program Workflow
• Testing
• Build & Deploy
• Scripts
• Troubleshooting
• Contributing
• Security
• License

---

Overview

• Dual-token design – Split a base reserve into stable (peg-focused) and reflexive (leveraged) claims. Recombine or transmute between them as market conditions change.
• Solana-native – Programs are written with Anchor, designed for composability with the broader Solana DeFi stack.
• Oracle-aware solvency – Pyth price feeds and internal health metrics drive fees, route availability, and guardrails against under-collateralization.
• Deterministic UX – The frontend provides clear flows for minting, redeeming, and transmutation, with typed clients generated from IDLs.

---

Architecture

Core mechanics

• Fission — Split base collateral into neutron (stable) and proton (leveraged) claims.
• Fusion — Recombine proton and neutron back into base collateral.
• Transmutation — Convert between claim types along protocol-defined routes (subject to fees/health).
• Decay/Reflexivity — System parameters modulate risk/return to keep reserves healthy and the peg robust.

Components

• Anchor Programs — On-chain accounting, mint/redeem/transmute instructions, fee logic, and guardrails.
• Pyth Oracles — External prices for solvency checks and parameterization.
• Next.js Frontend — Interaction console for user flows, wallet connectivity, and transaction previews.

---

Repository Layout

.
├── src/                   # Next.js (App Router) frontend
├── public/                # Static assets (logos, diagrams)
├── anchor/                # Anchor workspace: programs + tests
├── jest.config.js         # Jest config (incl. bankrun/localnet)
├── package.json           # Frontend + Anchor scripts
└── README.md

Key paths

• src/app/[coinId]/InteractionClient.tsx — UI for fission, fusion, transmutation.
• anchor/programs/ — Rust programs compiled by Anchor.
• anchor/tests/ — TypeScript integration tests for localnet/devnet.

---

Prerequisites

• Node.js ≥ 18 and npm ≥ 9 (or pnpm/yarn)
• Rust & Cargo (install via rustup)
• Solana CLI ≥ 1.18
• Anchor CLI ≥ 0.30

Verify:

node -v
solana --version
anchor --version

---

Configuration

Create a .env.local for the frontend:

NEXT_PUBLIC_SOLANA_NETWORK=devnet
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com
# Optional: surface on-chain IDs for programs/mints/reactors, e.g.:
# NEXT_PUBLIC_PROGRAM_ID=...
# NEXT_PUBLIC_NEUTRON_MINT=...
# NEXT_PUBLIC_PROTON_MINT=...

• Prefer a private RPC (Helius/Light/Triton) for better throughput.
• Anchor CLI also reads ~/.config/solana/cli/config.yml for cluster/wallet.

---

Quick Start (Frontend)

# 1) Install deps
npm install

# 2) Run the dev server
npm run dev
# → http://localhost:3000

If you change IDLs or generated clients, restart the dev server so types refresh.

---

Anchor Program Workflow

Most protocol logic lives in anchor/.

# 1) Build programs
npm run anchor-build

# 2) Start a local validator
solana-test-validator --reset
npm run anchor-localnet   # shortcut for `anchor localnet`

# 3) Deploy to local validator
cd anchor
anchor deploy

# 4) Test
npm run anchor-test        # anchor test runner (Rust + TS)
npm run test:anchor        # jest + bankrun (fast unit-style)
npm run test:devnet        # devnet tests (needs funded wallet + RPC)

anchor localnet spins up a validator and deploys built programs automatically.
Use solana-test-validator if you need fine-grained control or to side-load extra programs.

---

Testing

Target	Command	Notes
Anchor integration	npm run anchor-test	Executes Rust+TS tests against localnet via Anchor.
Jest (bankrun)	npm run test:anchor	Uses solana-bankrun for fast, deterministic checks.
Jest (devnet)	npm run test:devnet	Requires devnet wallet & RPC; exits on hanging handles.
Lint	npm run lint	Next.js/TypeScript preset.
Format	npm run format:check	Verify Prettier formatting (npm run format to apply).

Artifacts live in anchor/target/idl/,

---

Build & Deploy

Frontend

npm run build     # production build
npm run start     # preview locally (after build)

Deploy to Vercel/Cloudflare/Docker. Remember to set required env vars.

Contracts

npm run anchor-build

cd anchor
anchor keys list
anchor build
anchor deploy --provider.cluster devnet  

Export new program/mint/reactor IDs to the frontend via .env.local or src/config.

---

License

© 2025 Stability Nexus. All rights reserved.
If you intend to open-source this project, replace this section with the appropriate license (e.g., MIT/Apache-2.0) and add a LICENSE file.