Star Atlas Decoders

Rust decoders for Star Atlas Solana programs, generated from IDLs using Carbon CLI with custom patches for complex account deserialization.

Overview

This project generates and maintains Rust decoders for Star Atlas programs on Solana. It uses Carbon CLI to generate initial decoder code from program IDLs, then applies custom patches to handle complex account structures that require manual deserialization logic.

Supported Decoders

• sage-starbased: SAGE Starbase program (SAGE2HAwep459SNq61LHvjxPk4pLPEJLoMETef7f7EE)

  • Fleet and starbase management for Star Atlas
  • Custom patches for remaining data deserialization

• sage-holosim: SAGE Holosim program (SAgEeT8u14TE69JXtanGSgNkEdoPUcLabeyZD2uw8x9)

  • Fleet and starbase management for Star Atlas (uses local IDL)
  • Custom patches for remaining data deserialization

• atlas-staking: Atlas Staking program (ATLocKpzDbTokxgvnLew3d7drZkEzLzDpzwgrgWKDbmc)

  • ATLAS token staking with configurable rewards and cooldown periods
  • Minimal patches for serialization support

• locked-voter: Locked Voter program (Lock7kBijGCQLEFAmXcengzXKA88iDNQPriQ7TbgeyG)

  • POLIS governance and voting with escrow and whitelist controls
  • Minimal patches for serialization support

• marketplace: Galactic Marketplace program (traderDnaR5w6Tcoi3NFm53i48FTDNbGjBSZwWXDRrg)

  • NFT marketplace with order books, currency management, and royalty tiers
  • Minimal patches for serialization support

• atlas-fee-payer: ATLAS Fee Payer program (APR1MEny25pKupwn72oVqMH4qpDouArsX8zX4VwwfoXD)

  • Fee payment management for Star Atlas transactions
  • Minimal patches for serialization support

• cargo: Cargo program (Cargo2VNTPPTi9c1vq1Jw5d3BWUNr18MjRtSupAghKEk)

  • Resource container management with dynamic stat tracking
  • Custom patches for remaining data deserialization

• crafting: Crafting program (CRAFT2RPXPJWCEix4WpJST3E7NLf79GTqZUL75wngXo5)

  • Recipe-based item crafting with facilities and process tracking
  • Custom patches for type-safe enum handling and remaining data deserialization

• crew: Crew Management program (CREWiq8qbxvo4SKkAFpVnc6t7CRQC4tAAscsNAENXgrJ)

  • Crew management for Star Atlas ships and operations
  • Minimal patches for serialization support

• profile-vault: Profile Vault program (pv1ttom8tbyh83C1AVh6QH2naGRdVQUVt3HY1Yst5sv)

  • Profile vault management for Star Atlas player profiles
  • Minimal patches for serialization support

• srsly: Fleet Rentals (SRSLY) program (SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT)

  • Fleet rental contracts and automated payment processing
  • Custom patches for numeric field handling

• tcomp: Tensor cNFT Compressed program (TCMPhJdwDryooaGtiocG1u3xcYbRpiJzb283XfCZsDp)

  • Compressed NFT marketplace for trading cNFTs
  • Minimal patches for serialization support

• player-profile: Player Profile program (pprofELXjL5Kck7Jn5hCpwAL82DpTkSYBENzahVtbc9)

  • Player identity and role-based access control for Star Atlas
  • Custom patches for remaining data deserialization

• profile-faction: Profile Faction program (pFACSRuobDmvfMKq1bAzwj27t6d2GJhSCHb1VcfnRmq)

  • Player faction affiliation management for Star Atlas universe
  • Custom patches for type-safe faction handling

Prerequisites

Run ./scripts/check-tools.sh to verify all required tools are installed:

• Rust (1.75+ for edition 2024)
• Carbon CLI: cargo install --git https://github.com/sevenlabs-hq/carbon.git carbon-cli
• Just: cargo install just or brew install just
• Git and standard Unix tools (sed, find)

Quick Start

# Check required tools
./scripts/check-tools.sh

# Build all decoders and run CI checks
./scripts/ci.sh

Project Structure

star-atlas-decoders/
├── carbon-decoders/         # Published decoder crates
├── dist/                    # Temporary build directory (gitignored)
├── patches/                 # Custom patches for decoders
├── idl/                     # Local IDL files
├── scripts/                 # CI and utility scripts
│   ├── ci-clean.sh          # Full CI pipeline
│   ├── ci.sh                # GitHub CI pipeline
│   └── check-tools.sh       # Tool verification
├── docs/                    # Documentation
│   ├── adding-new-decoder.md
│   ├── patch-development-workflow.md
│   └── readmes/             # Individual decoder READMEs
└── justfile                 # Build automation

Development Workflow

Building Decoders

The build process follows these stages:

1. Generate: Fetch IDL and generate initial decoder code
2. Prepare: Fix compilation issues (array sizes, workspace refs)
3. Patch: Apply custom implementations for complex accounts
4. Publish: Move to workspace and verify compilation

# Full pipeline for a decoder
just all-sage-starbased

# Individual steps
just generate-sage-starbased   # Generate from IDL
just build-sage-starbased      # Clean + generate + prepare
just apply-patches-sage-starbased  # Apply custom patches
just publish-sage-starbased    # Move to workspace

Creating Custom Patches

Some accounts require custom deserialization for "remaining data" fields or dynamic arrays not in the IDL:

# 1. Build clean decoder
just build-sage-starbased

# 2. Apply existing patches
just apply-patches-sage-starbased

# 3. Edit files in dist/sage-starbased/
cd dist/sage-starbased
# Make your changes
vim src/accounts/fleet.rs

# 4. Test changes
cargo check

# 5. Create patch
just create-patch-sage-starbased my-change

# 6. Publish to workspace
just publish-sage-starbased

See docs/patch-development-workflow.md for detailed instructions.

Patch Naming Convention

When multiple patches need specific ordering, use numbered prefixes:

• sage-starbased-01-accounts.patch (applied first)
• sage-starbased-02-instructions.patch (applied second)

Common Commands

CI and Testing

# Run full CI pipeline
./scripts/ci.sh

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

# Run tests
cargo test --all

Maintenance

# Clean build artifacts
just clean-all

# List available patches
just list-patches

Custom Implementations

The decoders include custom deserialization for accounts with:

• Variable-length "remaining data" fields: e.g., Fleet's fleet_state, CargoType's cargo_stats, CargoPod's cargo_contents
• Dynamic arrays not in IDL: e.g., StarbasePlayer's ship_escrows, Profile's profile_keys
• Complex nested structures: Custom BorshDeserialize implementations

Example accounts with custom deserialization:

• Fleet: Includes fleet_state enum for current fleet activity
• StarbasePlayer: Includes dynamic ship_escrows list
• CargoType: Includes cargo_stats array (length = stats_count)
• CargoPod: Includes cargo_contents array of u64 values

For detailed patch implementations, see the patches/ directory and individual decoder READMEs in docs/readmes/.

Technical Details

• Rust Edition: 2024 (requires Rust 1.85.0+)
• Carbon Version: 0.10.0 (available on crates.io)
• Solana SDK: 2.x
• Platform: macOS and Linux compatible

Contributing

1. Follow the existing patch workflow for modifications
2. Ensure all changes pass ./scripts/ci.sh
3. Document any new custom deserializations
4. Use numbered patch prefixes when order matters

License

This project is licensed under the Apache-2.0 license.

Resources

• Carbon CLI Documentation
• Star Atlas Build