Estimated Effort: 2 weeks / 8 days
Impacted Subsystems / Files:
lib/phase-protocol.ts
lib/phase/rpc-client.ts
lib/phase/contract-calls.ts
lib/phase/xdr-builders.ts
lib/phase/ipfs-utils.ts
Context & Problem Statement: lib/phase-protocol.ts has grown into a 2,196-line monolith containing environment validation, contract ID resolution, RPC fallback proxies, base path inference, stroop math, XDR transaction builders, SEP-50 simulation helpers, IPFS gateway formatting, and catalog caching. This tight coupling makes unit testing impossible and causes client/server hydration mismatches.
Technical Requirements & Scope:
Extract contract ID and environment configuration into lib/phase/config.ts.
Isolate XDR transaction builders (buildSettleTransaction, buildInitiatePhaseTransaction) into lib/phase/xdr-builders.ts.
Separate read-only Soroban simulation calls into lib/phase/queries.ts.
Move IPFS gateway formatting (ipfsHttpsGatewayUrls) to lib/phase/ipfs-utils.ts.
Re-export public API from lib/phase-protocol.ts for backwards compatibility during transition.
Multi-File Change Surface: Touches lib/phase-protocol.ts and creates 5 new sub-modules. Impacted downstream consumers include every page in app/ and component in components/ importing protocol helpers.
Acceptance Criteria:
[ ] lib/phase-protocol.ts reduced from 2,196 lines to under 100 lines of barrel exports.
[ ] 100% unit test coverage achieved for isolated XDR builders and stroop conversion functions.
[ ] Zero client/server environment hydration warnings in browser console.
Suggested Approach / Investigation Steps:
Analyze import dependency graph of lib/phase-protocol.ts.
Create modular directory structure under lib/phase/.
Extract domain utilities step-by-step with dedicated unit tests.
Replace legacy monolithic imports across dApp components.
Estimated Effort: 2 weeks / 8 days
Impacted Subsystems / Files:
lib/phase-protocol.ts
lib/phase/rpc-client.ts
lib/phase/contract-calls.ts
lib/phase/xdr-builders.ts
lib/phase/ipfs-utils.ts
Context & Problem Statement: lib/phase-protocol.ts has grown into a 2,196-line monolith containing environment validation, contract ID resolution, RPC fallback proxies, base path inference, stroop math, XDR transaction builders, SEP-50 simulation helpers, IPFS gateway formatting, and catalog caching. This tight coupling makes unit testing impossible and causes client/server hydration mismatches.
Technical Requirements & Scope:
Extract contract ID and environment configuration into lib/phase/config.ts.
Isolate XDR transaction builders (buildSettleTransaction, buildInitiatePhaseTransaction) into lib/phase/xdr-builders.ts.
Separate read-only Soroban simulation calls into lib/phase/queries.ts.
Move IPFS gateway formatting (ipfsHttpsGatewayUrls) to lib/phase/ipfs-utils.ts.
Re-export public API from lib/phase-protocol.ts for backwards compatibility during transition.
Multi-File Change Surface: Touches lib/phase-protocol.ts and creates 5 new sub-modules. Impacted downstream consumers include every page in app/ and component in components/ importing protocol helpers.
Acceptance Criteria:
[ ] lib/phase-protocol.ts reduced from 2,196 lines to under 100 lines of barrel exports.
[ ] 100% unit test coverage achieved for isolated XDR builders and stroop conversion functions.
[ ] Zero client/server environment hydration warnings in browser console.
Suggested Approach / Investigation Steps:
Analyze import dependency graph of lib/phase-protocol.ts.
Create modular directory structure under lib/phase/.
Extract domain utilities step-by-step with dedicated unit tests.
Replace legacy monolithic imports across dApp components.