NiceChunk Programs

Solana native programs that define the persistent on-chain state of NiceChunk.

Official Links

GitHub: https://github.com/nicechunk/nicechunk-programs

Project Overview

This repository contains the native Solana program layer for NiceChunk. It is intentionally separated from the browser client so protocol work can be reviewed, tested, audited, and forked without pulling in frontend assets or deployment concerns.

The current program set covers the global genesis configuration, player profile and session authority, chunk mutation and generated-block verification, Guardian registry and region staking, transferable backpack storage, marketplace settlement, land contracts, and NCM3 buildings. These programs are small, explicit, and account-layout driven.

The repository also includes operational scripts and TypeScript helpers used to derive PDAs, initialize devnet state, inspect generated blocks, mine blocks, register Guardians, and validate global configuration accounts.

Program Domain Mesh

The program set is deliberately split by gameplay domain. Core stores sealed world and economy configuration. Player owns identity, position, equipment, and session authority. Chunk owns generated-block verification, block deltas, mining, land indexes, and delegation hooks. Guardian owns region registration and proof state. Backpack owns portable resource records. Market owns listings, treasury-issued contract balances, and settlement state. Building reserves and consumes contracts while registering chunk-aligned land, then stores versioned NCM3 building manifests and shards.

This layout keeps account review small. A change to marketplace listing state should not require a reviewer to re-audit player sessions. A change to chunk verification should stay visible next to the SDK decoder and tests that depend on the same byte layout.

Account Layout Review

The strongest habit in this repository should be account-layout discipline. A program state change starts in Rust, but it is not complete until the instruction layer, SDK decoder, scripts, tests, and documentation all agree on the same magic header, length, seed order, and field offsets.

That is the review path future contributors should follow. The repository should make byte-level changes boring to inspect: what changed, which account owns it, which instruction writes it, which SDK decoder reads it, and which test proves the new shape.

System Principles

• Immutable public configuration: the core program stores fixed world and economy parameters, including hashes for terrain and resource rules, so clients can compare runtime behavior against public configuration.
• Native Solana account layouts: each program uses compact byte layouts and explicit PDA seeds rather than framework-generated account metadata.
• Program boundaries mirror gameplay domains: player identity, chunk state, Guardian coverage, backpack inventory, market settlement, and building storage are isolated so future upgrades can target the smallest possible surface.
• Frontend compatibility is treated as a contract: SDK decoders and scripts are kept near program sources so layout changes are visible during development.

How It Works

• Build programs with Cargo using the desired cluster feature, usually devnet during current development.
• Use the scripts directory to derive PDAs and initialize chain state from the same constants used by the SDK.
• Run focused tests for layout and instruction behavior before publishing new program IDs or account layout changes.
• When a layout changes, update the matching SDK decoder and the contract directory page in the same development cycle.

Land Contract Lifecycle

• A player joins the market once to create the owner-funded market-user-v1 PDA.
• The Market program sells blank land contracts from the NICECHUNK treasury at a fixed price of 10 NCK each. Treasury sales do not create Listing PDAs.
• One blank land contract represents one complete 16 x 16 horizontal chunk. A rectangular parcel consumes chunksX * chunksZ contracts, with a protocol limit of 4,096 contracts per parcel.
• Creating a build-site-v3 PDA moves the required balance into a reserved counter before any chunk index is committed.
• The Building program registers foundation-chunk-v3 indexes in deterministic batches. The final batch consumes the reservation atomically with BuildSite activation.
• If indexing cannot finish, cancellation removes committed indexes in reverse order and restores the complete reservation before closing the incomplete BuildSite.
• Active land cannot be resized or canceled. Buildings use the separate building-v3 manifest namespace and remain bound to one active parcel.

The retired Blueprint inventory and v2 foundation/building namespaces are not accepted by the new flow. Legacy Blueprint backpack records are filtered and compacted during later inventory writes; old v2 accounts remain historical chain data but are not loaded as active land or buildings.

Treasury Swap

The Market domain also includes an opt-in fixed-rate SOL <-> NCK treasury exchange. User trades settle atomically against program-controlled SOL and NCK reserve PDAs; only the fixed NICECHUNK treasury wallet may configure, pause, fund, or withdraw those reserves. Every trade commits to a configuration revision, deadline slot, and minimum output, and all value math uses checked integer arithmetic with conservative rounding.

Initialization is deliberately paused and contains no guessed exchange rate. Reserve withdrawals require a paused exchange, and activation verifies that both PDA reserves cover the configured maximum single trade. See Treasury Swap for the custody model, account seeds, formulas, dry-run administrator workflow, and activation checklist. TypeScript account decoding and instruction builders are in sdk/nicechunk-market.ts.

Why This Project Matters

NiceChunk depends on verifiable game state. This repository provides the part of the system that cannot be replaced by UI code: public account ownership, deterministic PDAs, explicit state transitions, and economic settlement primitives.

Splitting the programs makes protocol review easier. A contributor can fork the on-chain layer, audit instruction handlers, or prototype a new program without dealing with browser rendering, media assets, or deployment configuration.

Repository Layout

• programs/
• sdk/
• scripts/
• tests/
• docs/

Development Workflow

1. Clone the repository and inspect the focused source tree before changing shared contracts or generated artifacts.
2. Keep changes scoped to the domain of this repository. Cross-domain changes should be coordinated through the matching split repositories.
3. Run the smallest meaningful validation for the touched surface: build checks for programs, browser checks for pages, or fixture checks for deterministic libraries.
4. Update screenshots and documentation when behavior, visible UI, public constants, or developer-facing workflows change.

Future Development Direction

• Add stronger integration tests for cross-program flows such as session-authorized mining into backpack storage and market listing settlement.
• Publish stable account-layout documentation and versioned changelogs for each program.
• Separate generated client bindings from hand-written SDK helpers once the protocol reaches a stable release boundary.
• Prepare mainnet feature flags, deployment checklists, and reproducible build metadata before any production program deployment.

Maintenance Notes

This repository is a focused split from the main NiceChunk working tree. Keep the public surface explicit: avoid committing private keys, wallet files, deployment-only scripts, machine-specific configuration, or generated build artifacts. Runtime user-facing copy should stay behind the i18n layer where the project has an i18n surface.