Decompose coinset parse into focused submodules (#158)

* Decompose coinset parse into focused modules with unified RPC checks.

Split parse, pagination, and utility concerns into dedicated modules so JSON parsing, cursor pagination, and RPC success handling each have a clear home without changing the public coinset API.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Tighten coinset decomposition and document layout in ADR 0018.

Inline unspent record filtering, fold pagination response parsing into cursor, adopt to_coinset_hex across in-crate callers, and record the submodule ownership split.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Record coinset parse decomposition milestone in progress log.

Document the #158 submodule refactor and ADR 0018 reference alongside other 2026-06-29 decomposition milestones.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hoffmang9

docs/README.md

@@ -7,6 +7,7 @@ accepted decision** when onboarding.
 
 | ADR                                                              | Topic                                                                   |
 | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [0018](decisions/0018-coinset-parse-decomposition.md)            | **Coinset submodule layout** — parse, pagination, rpc_result, json_util |
 | [0017](decisions/0017-offer-submodule-decompositions.md)         | **Offer submodule layout** — bootstrap planner/phase + presplit         |
 | [0015](decisions/0015-on-chain-offer-cancel.md)                  | **On-chain offer cancel** — reclaim spend, `cancel_submitted` lifecycle |
 | [0014](decisions/0014-offer-publish-module-decomposition.md)     | **Offer publish decomposition** — bootstrap gate + publish assets       |

docs/decisions/0018-coinset-parse-decomposition.md

@@ -0,0 +1,58 @@
+# ADR 0018: Coinset parse and pagination submodule decomposition
+
+## Status
+
+Accepted (2026-06-29)
+
+## Context
+
+`coinset/parse.rs` (~440 lines) mixed JSON payload parsing, typed coin-record helpers,
+RPC success checks, pagination field extraction, and generic utilities (`chunk_values`,
+`to_coinset_hex`). `pagination.rs` mixed cursor parsing with async page orchestration.
+Callers imported from a single `parse` module name that no longer matched its contents.
+
+## Decision
+
+### Coinset layout (`greenfloor-engine/src/coinset/`)
+
+| Module                 | Responsibility                                                                                             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `parse/mod.rs`         | Barrel re-exports for JSON → protocol parsing only                                                         |
+| `parse/payload.rs`     | `coin_records_from_payload`, `record_from_payload`                                                         |
+| `parse/record.rs`      | `coin_id_from_record`, `coin_from_record`, `coin_spend_from_solution_payload`                              |
+| `parse/tests.rs`       | Parse unit tests                                                                                           |
+| `rpc_result.rs`        | `ensure_coinset_success` (typed SDK responses), `ensure_coinset_rpc_success` (JSON payloads)               |
+| `pagination/mod.rs`    | Async cursor page orchestration (`fetch_all_coinset_pages`, endpoint wrappers)                             |
+| `pagination/cursor.rs` | `CoinsetRecordsPagination`, `pagination_from_*`, `ensure_complete_page`, `coin_records_page_from_response` |
+| `pagination/tests.rs`  | Pagination unit tests                                                                                      |
+| `json_util.rs`         | Coinset JSON scan helpers: `to_coinset_hex`, `u64_from_value`                                              |
+| `batch.rs`             | Generic `chunk_values` batching for scan/lineage queries                                                   |
+
+**Ownership split:**
+
+- **`rpc_result`** owns Coinset RPC success/failure mapping for typed and JSON responses.
+- **`parse`** owns JSON coin-record and spend decoding only.
+- **`pagination`** owns cursor pagination types, page parsing, and multi-page fetch loops.
+- **`json_util`** is the canonical in-crate `0x`-prefixed hex helper for Coinset IO (`wallet_io`, scan paths).
+
+Unspent typed `CoinRecord` filtering (`!record.spent`) is inlined at call sites in `xch`,
+`coin_select`, and `cats/list` — a one-line filter does not warrant a shared module.
+
+**Public API:** `greenfloor_engine::coinset::*` re-exports are unchanged (`chunk_values`,
+`to_coinset_hex`, `u64_from_value`, `ensure_coinset_rpc_success`, parse fns).
+
+**Behavior note:** `coin_spend_from_solution_payload` uses `hex_to_bytes` (normalize + strip
+non-hex) instead of raw `hex::decode(trim_start_matches("0x"))`; tests document the broader
+acceptance of prefixed/mixed-case hex.
+
+## Consequences
+
+- Import `ensure_coinset_success` from `coinset::rpc_result` (crate-internal), not `parse`.
+- Import pagination helpers from `coinset::pagination`, not `parse`.
+- Prefer `json_util::to_coinset_hex` over local `format!("0x{}", hex::encode(...))` in `coinset/`.
+- Historical references to monolithic `parse.rs` / `pagination.rs` are superseded by this ADR.
+
+## References
+
+- [0007](0007-rust-signer-and-coinset-io.md) — Rust Coinset IO baseline
+- [0017](0017-offer-submodule-decompositions.md) — prior submodule decomposition pattern

docs/progress.md

@@ -16,6 +16,14 @@ Pre-Rust migration detail lives in git history and
 
 ## Milestones
 
+### 2026-06-29 — Coinset parse and pagination decomposed (#158)
+
+Split monolithic `coinset/parse.rs` into `parse/{payload,record,tests}.rs`; extracted
+`rpc_result`, `json_util`, and `batch`. Split `pagination.rs` into `pagination/` with cursor
+parsing in `cursor.rs` and async page orchestration in `mod.rs`. Unified typed and JSON RPC
+success checks; inlined unspent `CoinRecord` filtering; adopted `to_coinset_hex` across in-crate
+callers. Public `greenfloor_engine::coinset::*` re-exports unchanged. See ADR 0018.
+
 ### 2026-06-29 — Bootstrap phase mapping refactored (#157)
 
 Decomposed `offer/bootstrap/phase.rs` into `phase/mod.rs` + `phase/tests.rs`. Typed

greenfloor-engine/src/coinset/api/rpc.rs

@@ -3,8 +3,8 @@ use serde_json::{json, Value};
 
 use super::super::{
     direct_api,
-    pagination::coin_records_from_json_endpoint,
-    parse::{coin_records_from_payload, pagination_from_payload, record_from_payload},
+    pagination::{coin_records_from_json_endpoint, pagination_from_payload},
+    parse::{coin_records_from_payload, record_from_payload},
     retry::with_script_retries,
 };
 use crate::error::{SignerError, SignerResult};

greenfloor-engine/src/coinset/batch.rs

@@ -0,0 +1,34 @@
+pub fn chunk_values<T: Clone>(values: &[T], chunk_size: usize) -> Vec<Vec<T>> {
+    if chunk_size == 0 {
+        return if values.is_empty() {
+            Vec::new()
+        } else {
+            vec![values.to_vec()]
+        };
+    }
+    values.chunks(chunk_size).map(<[T]>::to_vec).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::chunk_values;
+
+    #[test]
+    fn chunk_values_respects_batch_size() {
+        let values = vec!["a".to_string(), "b".to_string(), "c".to_string()];
+        assert_eq!(
+            chunk_values(&values, 2),
+            vec![
+                vec!["a".to_string(), "b".to_string()],
+                vec!["c".to_string()]
+            ]
+        );
+    }
+
+    #[test]
+    fn chunk_values_zero_batch_returns_single_chunk() {
+        let values = vec![1, 2, 3];
+        assert_eq!(chunk_values(&values, 0), vec![vec![1, 2, 3]]);
+        assert!(chunk_values::<i32>(&[], 2).is_empty());
+    }
+}

greenfloor-engine/src/coinset/broadcast.rs

@@ -2,7 +2,7 @@ use chia_protocol::SpendBundle;
 use chia_sdk_coinset::{ChiaRpcClient, CoinsetClient};
 use chia_traits::Streamable;
 
-use super::parse::ensure_coinset_typed_rpc_success;
+use super::rpc_result::ensure_coinset_success;
 use crate::error::SignerResult;
 use crate::hex::canonical_tx_id;
 
@@ -31,7 +31,11 @@ pub async fn broadcast_spend_bundle(
         .push_tx(spend_bundle)
         .await
         .map_err(crate::error::SignerError::from)?;
-    ensure_coinset_typed_rpc_success(&response, "push_tx failed")?;
+    ensure_coinset_success(
+        response.success,
+        response.error.as_deref(),
+        "push_tx failed",
+    )?;
     Ok(BroadcastSpendBundleResult {
         status: response.status,
         operation_id,

greenfloor-engine/src/coinset/cats/list.rs

@@ -4,7 +4,7 @@ use chia_sdk_coinset::{ChiaRpcClient, CoinRecord, CoinsetClient};
 use chia_sdk_driver::Cat;
 use futures_util::future::try_join_all;
 
-use super::{resolve, unspent_coin_records};
+use super::resolve;
 use crate::bech32m::decode_address;
 use crate::coinset::pagination::coin_records_by_puzzle_hash;
 use crate::coinset::retry::with_coinset_client_retries;
@@ -90,7 +90,7 @@ async fn unspent_cats_from_records(
     client: &CoinsetClient,
     records: Vec<CoinRecord>,
 ) -> SignerResult<Vec<Cat>> {
-    let records: Vec<CoinRecord> = unspent_coin_records(records).collect();
+    let records: Vec<CoinRecord> = records.into_iter().filter(|record| !record.spent).collect();
     cats_with_lineage_from_records(client, &records).await
 }
 

greenfloor-engine/src/coinset/cats/mod.rs

@@ -1,7 +1,6 @@
 mod list;
 mod resolve;
 
-pub(crate) use super::parse::unspent_coin_records;
 pub(crate) use list::{coin_records_for_cat_outer_puzzle_hash, coin_records_for_coin_ids};
 pub use list::{list_unspent_cats, list_unspent_cats_by_ids};
 pub(crate) use resolve::cat_from_record;

greenfloor-engine/src/coinset/coin_select/mod.rs

@@ -9,7 +9,6 @@ use chia_sdk_driver::Cat;
 use super::cats::{
     cat_from_record, coin_records_for_cat_outer_puzzle_hash, coin_records_for_coin_ids,
 };
-use super::parse::unspent_coin_records;
 use crate::error::{SignerError, SignerResult};
 
 /// Minimum CAT output amount for offer/dust policy (1000 mojos = 1 CAT unit).
@@ -186,12 +185,17 @@ pub(crate) async fn select_cats_for_spend(
     target_amount: u64,
 ) -> SignerResult<SelectedCats> {
     let records = if explicit_coin_ids.is_empty() {
-        unspent_coin_records(
-            coin_records_for_cat_outer_puzzle_hash(client, receive_address, asset_id).await?,
-        )
-        .collect()
+        coin_records_for_cat_outer_puzzle_hash(client, receive_address, asset_id)
+            .await?
+            .into_iter()
+            .filter(|record| !record.spent)
+            .collect()
     } else {
-        unspent_coin_records(coin_records_for_coin_ids(client, explicit_coin_ids).await?).collect()
+        coin_records_for_coin_ids(client, explicit_coin_ids)
+            .await?
+            .into_iter()
+            .filter(|record| !record.spent)
+            .collect()
     };
     select_cats_for_spend_from_records(client, records, explicit_coin_ids, target_amount).await
 }

greenfloor-engine/src/coinset/json_util.rs

@@ -0,0 +1,33 @@
+#[must_use]
+pub fn to_coinset_hex(bytes: &[u8]) -> String {
+    format!("0x{}", hex::encode(bytes))
+}
+
+#[must_use]
+pub fn u64_from_value(value: Option<&serde_json::Value>, default: u64) -> u64 {
+    value
+        .and_then(|raw| {
+            raw.as_u64()
+                .or_else(|| raw.as_i64().and_then(|v| u64::try_from(v).ok()))
+        })
+        .unwrap_or(default)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn to_coinset_hex_prefixes_0x() {
+        assert_eq!(to_coinset_hex(&[0xab]), "0xab");
+    }
+
+    #[test]
+    fn u64_from_value_prefers_u64_and_parses_i64() {
+        assert_eq!(u64_from_value(Some(&json!(42_u64)), 0), 42);
+        assert_eq!(u64_from_value(Some(&json!(7_i64)), 0), 7);
+        assert_eq!(u64_from_value(Some(&json!("bad")), 99), 99);
+        assert_eq!(u64_from_value(None, 5), 5);
+    }
+}