feat: add cargo decoder (#35)

### TL;DR

Added a new Cargo program decoder for Star Atlas resource container management.

### What changed?

- Added a new `carbon-cargo-decoder` crate for the Star Atlas Cargo program (`Cargo2VNTPPTi9c1vq1Jw5d3BWUNr18MjRtSupAghKEk`)
- Implemented account types: `CargoPod`, `CargoType`, and `CargoStatsDefinition`
- Added instruction parsing for all Cargo program instructions
- Created custom `CargoPermissions` bitflags with helper methods for permission management
- Added serialization support for account types
- Updated README, justfile, and project documentation to include the new decoder

### Why make this change?

The Cargo program is a critical component of the Star Atlas ecosystem, managing resource containers (pods) with dynamic stat tracking and cargo types. This decoder enables developers to interact with and analyze Cargo program data, supporting use cases like resource management, inventory tracking, and game economy analysis. The custom permission bitflags provide an ergonomic way to work with the program's permission system.

Author: ttdonovan

Cargo.lock

@@ -28,6 +28,9 @@
   <a href="https://crates.io/crates/carbon-atlas-fee-payer-decoder">
     <img src="https://img.shields.io/crates/v/carbon-atlas-fee-payer-decoder?logo=rust&label=atlas-fee-payer" />
   </a>
+  <a href="https://crates.io/crates/carbon-cargo-decoder">
+    <img src="https://img.shields.io/crates/v/carbon-cargo-decoder?logo=rust&label=cargo" />
+  </a>
   <a href="https://crates.io/crates/carbon-crew-decoder">
     <img src="https://img.shields.io/crates/v/carbon-crew-decoder?logo=rust&label=crew" />
   </a>
@@ -57,66 +60,56 @@ This project generates and maintains Rust decoders for Star Atlas programs on So
 ### Supported Decoders
 
 - **sage-starbased**: SAGE Starbase program (`SAGE2HAwep459SNq61LHvjxPk4pLPEJLoMETef7f7EE`)
-  - Fetches IDL directly from Solana mainnet
-  - Custom deserialization for Fleet and StarbasePlayer accounts
+  - Fleet and starbase management for Star Atlas
+  - Custom patches for remaining data deserialization
 
 - **sage-holosim**: SAGE Holosim program (`SAgEeT8u14TE69JXtanGSgNkEdoPUcLabeyZD2uw8x9`)
-  - Uses local IDL file from `./idl/` directory
-  - Custom deserialization for Fleet and StarbasePlayer accounts
+  - Fleet and starbase management for Star Atlas (uses local IDL)
+  - Custom patches for remaining data deserialization
 
 - **atlas-staking**: Atlas Staking program (`ATLocKpzDbTokxgvnLew3d7drZkEzLzDpzwgrgWKDbmc`)
-  - Fetches IDL directly from Solana mainnet
   - ATLAS token staking with configurable rewards and cooldown periods
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **locked-voter**: Locked Voter program (`Lock7kBijGCQLEFAmXcengzXKA88iDNQPriQ7TbgeyG`)
-  - Fetches IDL directly from Solana mainnet
   - POLIS governance and voting with escrow and whitelist controls
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **marketplace**: Galactic Marketplace program (`traderDnaR5w6Tcoi3NFm53i48FTDNbGjBSZwWXDRrg`)
-  - Fetches IDL directly from Solana mainnet
   - NFT marketplace with order books, currency management, and royalty tiers
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **atlas-fee-payer**: ATLAS Fee Payer program (`APR1MEny25pKupwn72oVqMH4qpDouArsX8zX4VwwfoXD`)
-  - Fetches IDL directly from Solana mainnet
   - Fee payment management for Star Atlas transactions
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
+
+- **cargo**: Cargo program (`Cargo2VNTPPTi9c1vq1Jw5d3BWUNr18MjRtSupAghKEk`)
+  - Resource container management with dynamic stat tracking
+  - Custom patches for remaining data deserialization
 
 - **crew**: Crew Management program (`CREWiq8qbxvo4SKkAFpVnc6t7CRQC4tAAscsNAENXgrJ`)
-  - Fetches IDL directly from Solana mainnet
   - Crew management for Star Atlas ships and operations
-  - Uses serde_big_array for large byte arrays
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **profile-vault**: Profile Vault program (`pv1ttom8tbyh83C1AVh6QH2naGRdVQUVt3HY1Yst5sv`)
-  - Fetches IDL directly from Solana mainnet
   - Profile vault management for Star Atlas player profiles
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **srsly**: Fleet Rentals (SRSLY) program (`SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT`)
-  - Fetches IDL directly from Solana mainnet
   - Fleet rental contracts and automated payment processing
-  - Custom patches - adds serialization support and f64 rate field workaround
+  - Custom patches for numeric field handling
 
 - **tcomp**: Tensor cNFT Compressed program (`TCMPhJdwDryooaGtiocG1u3xcYbRpiJzb283XfCZsDp`)
-  - Fetches IDL directly from Solana mainnet
   - Compressed NFT marketplace for trading cNFTs
-  - Uses serde_big_array for large byte arrays
-  - Minimal patches needed - adds serialization support for account types
+  - Minimal patches for serialization support
 
 - **player-profile**: Player Profile program (`pprofELXjL5Kck7Jn5hCpwAL82DpTkSYBENzahVtbc9`)
-  - Fetches IDL directly from Solana mainnet
   - Player identity and role-based access control for Star Atlas
-  - Custom patches - adds serialization and ergonomic permission bitflags with helper methods
-  - Includes permission checking, key expiration validation, and role management
+  - Custom patches for remaining data deserialization
 
 - **profile-faction**: Profile Faction program (`pFACSRuobDmvfMKq1bAzwj27t6d2GJhSCHb1VcfnRmq`)
-  - Fetches IDL directly from Solana mainnet
   - Player faction affiliation management for Star Atlas universe
-  - Custom patches - adds serialization and type-safe Faction enum
-  - Supports Unaligned, MUD, ONI, and Ustur factions
+  - Custom patches for type-safe faction handling
 
 ## Prerequisites
 
@@ -142,46 +135,18 @@ Run `./scripts/check-tools.sh` to verify all required tools are installed:
 ```
 star-atlas-decoders/
 ├── carbon-decoders/         # Published decoder crates
-│   ├── sage-starbased-decoder/
-│   ├── sage-holosim-decoder/
-│   ├── atlas-staking-decoder/
-│   ├── locked-voter-decoder/
-│   ├── marketplace-decoder/
-│   ├── atlas-fee-payer-decoder/
-│   ├── crew-decoder/
-│   ├── profile-vault-decoder/
-│   ├── srsly-decoder/
-│   ├── tcomp-decoder/
-│   ├── player-profile-decoder/
-│   └── profile-faction-decoder/
 ├── dist/                    # Temporary build directory (gitignored)
 ├── patches/                 # Custom patches for decoders
-│   ├── sage-starbased-01-accounts.patch
-│   ├── sage-holosim-01-disable-ix-combat-log-event.patch
-│   ├── atlas-staking-01-accounts-serialize.patch
-│   ├── locked-voter-01-accounts-serialize.patch
-│   ├── marketplace-01-accounts-serialize.patch
-│   ├── atlas-fee-payer-01-accounts-serialize.patch
-│   ├── crew-01-accounts-serialize.patch
-│   ├── profile-vault-01-accounts-serialize.patch
-│   ├── srsly-01-accounts-serialize.patch
-│   ├── srsly-02-rate-f64-workaround.patch
-│   ├── tcomp-01-accounts-serialize.patch
-│   ├── player-profile-01-accounts-serialize.patch
-│   ├── player-profile-02-permissions-helpers.patch
-│   ├── player-profile-03-remaining-data.patch
-│   └── player-profile-04-instruction-remaining-accounts.patch
-│   ├── profile-faction-01-accounts-serialize.patch
-│   └── profile-faction-02-use-faction-enum.patch
 ├── idl/                     # Local IDL files
 ├── scripts/                 # CI and utility scripts
-│   ├── ci.sh               # Full CI pipeline
-│   └── check-tools.sh      # Tool verification
+│   ├── 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
-
+│   └── readmes/             # Individual decoder READMEs
+└── justfile                 # Build automation
 ```
 
 ## Development Workflow
@@ -269,13 +234,17 @@ just list-patches
 
 The decoders include custom deserialization for accounts with:
 
-- **Variable-length "remaining data" fields**: e.g., Fleet's `fleet_state`
-- **Dynamic arrays not in IDL**: e.g., StarbasePlayer's `ship_escrows`
+- **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
 

README.md

@@ -0,0 +1,26 @@
+[package]
+name = "carbon-cargo-decoder"
+version = "0.10.0"
+edition = "2024"
+description = "Rust decoder for Star Atlas Cargo program on Solana"
+license = "Apache-2.0"
+repository = "https://github.com/staratlasmeta/star-atlas-decoders"
+homepage = "https://github.com/staratlasmeta/star-atlas-decoders"
+readme = "README.md"
+keywords = ["solana", "star-atlas", "decoder"]
+categories = ["encoding"]
+rust-version = "1.85"
+
+[lib]
+crate-type = ["rlib"]
+
+[dependencies]
+bitflags = "2.6"
+carbon-core = "0.10.0"
+carbon-proc-macros = "0.10.0"
+carbon-macros = "0.10.0"
+solana-account = "2.2.1"
+solana-instruction = { version = "2.3.0", default-features = false }
+solana-pubkey = { version = "2.4.0", features = ["borsh", "serde", "bytemuck"] }
+serde = { version = "1.0", features = ["derive"] }
+

carbon-decoders/cargo-decoder/Cargo.toml

@@ -0,0 +1,127 @@
+# Carbon Cargo Decoder
+
+<p align="center">
+  <a href="https://crates.io/crates/carbon-cargo-decoder">
+    <img src="https://img.shields.io/crates/v/carbon-cargo-decoder?logo=rust" />
+  </a>
+  <a href="https://docs.rs/carbon-cargo-decoder">
+    <img src="https://img.shields.io/docsrs/carbon-cargo-decoder?logo=docsdotrs" />
+  </a>
+  <a href="https://github.com/staratlasmeta/star-atlas-decoders/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-Apache%202.0-blue" />
+  </a>
+</p>
+
+Rust decoder for the Star Atlas Cargo program on Solana, generated using [Carbon CLI](https://github.com/sevenlabs-hq/carbon).
+
+## Program Information
+
+- **Program ID**: `Cargo2VNTPPTi9c1vq1Jw5d3BWUNr18MjRtSupAghKEk`
+- **Network**: Solana Mainnet
+- **Description**: Star Atlas Cargo program for managing resource containers (pods) with dynamic stat tracking, cargo types, and token-based resource management.
+
+## Features
+
+- Decodes all Cargo account types
+- Full instruction parsing support
+- Integration with Carbon indexing framework
+- Permission bitflags support for cargo operations
+- Support for dynamic cargo stats and pod management
+
+## Usage
+
+Add this crate to your `Cargo.toml`:
+
+```toml
+[dependencies]
+carbon-cargo-decoder = "0.10.0"
+```
+
+### Decoding Accounts
+
+```rust
+use carbon_cargo_decoder::{CargoDecoder, CargoAccount};
+use carbon_core::account::AccountDecoder;
+
+let decoder = CargoDecoder;
+let decoded_account = decoder.decode_account(&account);
+
+if let Some(decoded) = decoded_account {
+    match decoded.data {
+        CargoAccount::CargoPod(pod) => {
+            println!("Cargo Pod: {:?}", pod);
+            println!("Authority: {}", pod.authority);
+            println!("Open Token Accounts: {}", pod.open_token_accounts);
+        }
+        CargoAccount::CargoType(cargo_type) => {
+            println!("Cargo Type: {:?}", cargo_type);
+            println!("Mint: {}", cargo_type.mint);
+            println!("Stats Count: {}", cargo_type.stats_count);
+        }
+        CargoAccount::CargoStatsDefinition(definition) => {
+            println!("Stats Definition: {:?}", definition);
+            println!("Authority: {}", definition.authority);
+            println!("Sequence ID: {}", definition.seq_id);
+        }
+    }
+}
+```
+
+### Working with Permissions
+
+The decoder includes ergonomic permission handling with bitflags:
+
+```rust
+use carbon_cargo_decoder::CargoPermissions;
+
+// Create permissions from u64 or bytes
+let perms = CargoPermissions::from_u64(0b111);
+
+// Check individual permissions
+if perms.contains(CargoPermissions::MANAGE_DEFINITION) {
+    println!("Can manage cargo definitions");
+}
+
+if perms.contains(CargoPermissions::CREATE_CARGO_TYPE) {
+    println!("Can create new cargo types");
+}
+
+if perms.contains(CargoPermissions::MANAGE_CARGO_TYPE) {
+    println!("Can update existing cargo types");
+}
+
+// Combine permissions
+let admin_perms = CargoPermissions::MANAGE_DEFINITION
+    | CargoPermissions::CREATE_CARGO_TYPE
+    | CargoPermissions::MANAGE_CARGO_TYPE;
+
+// Convert to/from bytes for storage
+let bytes = admin_perms.to_le_bytes();
+let restored = CargoPermissions::from_le_bytes(bytes);
+```
+
+### Account Types
+
+This decoder supports all Cargo account types:
+- `CargoPod` - Container for resources with dynamic stat tracking
+- `CargoType` - Definition of a specific cargo type with associated stats
+- `CargoStatsDefinition` - Global configuration for cargo stat definitions
+
+### Permission Flags
+
+The `CargoPermissions` bitflags type includes:
+- `MANAGE_DEFINITION` - Can initialize and update cargo definitions
+- `CREATE_CARGO_TYPE` - Can create new cargo types
+- `MANAGE_CARGO_TYPE` - Can update existing cargo types
+
+## Documentation
+
+Full documentation is available at [docs.rs](https://docs.rs/carbon-cargo-decoder).
+
+## Repository
+
+See the [main repository](https://github.com/staratlasmeta/star-atlas-decoders) for build instructions and contribution guidelines.
+
+## License
+
+Licensed under the [Apache-2.0](https://github.com/staratlasmeta/star-atlas-decoders/blob/main/LICENSE) license.