Skip to content

Commit 36c09f6

Browse files
committed
Fix spec inconsistencies: align with x402 MCP spec, resolve task numbering collision, add missing tests
- Remove invalid FR-009/FR-010 (HTTP headers), replace with official x402 MCP transport spec reference - Fix task numbering collision: renumber T050-T092 to T054-T098 (now 98 tasks total) - Add T009: Payment requirement validation helpers - Add T036: Settlement response extraction from error.data test - Add T083-T086: JSON-RPC protocol error tests (-32700, -32602, -32603, -32601) - Fix middleware.go references to handler.go (T063, plan.md) - Update all FR cross-references (FR-017/018 → FR-015/016) - Update task cross-references in dependency sections and parallel execution examples Resolves: 7 critical/high-priority specification analysis issues - S1: Invalid HTTP header requirements contradicting official spec - D1: Task numbering collision (T050-T055 duplicated T009-T015 range) - I1: Incorrect middleware.go file references - I2: Outdated ToolHandlerMiddleware pattern mention - M1: Missing settlement-in-error-data test per x402 MCP spec - M2: Missing JSON-RPC protocol error tests - U1: Missing payment requirement validation All specs now align with: - Official x402 MCP transport spec (github.com/coinbase/x402) - Existing x402-go selector.go implementation - Project constitution principles
1 parent 73281a3 commit 36c09f6

File tree

6 files changed

+307
-180
lines changed

6 files changed

+307
-180
lines changed

.beads/issues.jsonl

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{"id":"x402-go-1","title":"Remove DEBUG log statements from production code","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-29T17:25:43.770299599+03:00","updated_at":"2025-10-29T20:14:38.315218628+03:00","closed_at":"2025-10-29T20:14:38.315218628+03:00"}
2-
{"id":"x402-go-10","title":"Add godoc package documentation for all public packages","description":"Add godoc package documentation for all public packages. CDP signer (signers/coinbase) already has comprehensive GoDoc comments. Still needed for: http/, evm/, svm/, and root package.","status":"open","priority":3,"issue_type":"task","created_at":"2025-10-29T17:26:00.049130692+03:00","updated_at":"2025-10-30T15:06:57.195088706+03:00"}
2+
{"id":"x402-go-10","title":"Add godoc package documentation for all public packages","description":"Add godoc package documentation for all public packages. CDP signer (signers/coinbase) already has comprehensive GoDoc comments. Still needed for: http/, evm/, svm/, and root package.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-29T17:26:00.049130692+03:00","updated_at":"2025-10-31T15:03:03.521036782+03:00","closed_at":"2025-10-31T15:03:03.521036782+03:00"}
33
{"id":"x402-go-11","title":"types.go AmountToBigInt silently discards accuracy information","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-29T17:26:00.871179508+03:00","updated_at":"2025-10-29T20:14:36.210574163+03:00","closed_at":"2025-10-29T20:14:36.210574163+03:00"}
44
{"id":"x402-go-12","title":"http/client.go GetSettlement silently returns nil on parse errors","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-29T17:26:01.295078602+03:00","updated_at":"2025-10-29T20:14:35.399267019+03:00","closed_at":"2025-10-29T20:14:35.399267019+03:00"}
55
{"id":"x402-go-13","title":"http/facilitator.go should have configurable retry logic for facilitator failures","description":"","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-10-29T17:26:01.361852264+03:00","updated_at":"2025-10-29T20:14:34.460462839+03:00","closed_at":"2025-10-29T20:14:34.460462839+03:00"}
@@ -10,11 +10,26 @@
1010
{"id":"x402-go-18","title":"Phase 9: Polish and documentation for CDP signer","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-30T14:53:58.7000909+03:00","updated_at":"2025-10-30T15:03:12.358091619+03:00","closed_at":"2025-10-30T15:03:12.358091619+03:00"}
1111
{"id":"x402-go-19","title":"CDP Signer Implementation Complete - PR #10","description":"CDP signer implementation complete and merged in PR #10.\n\n**Implementation:**\n- 11 new files in signers/coinbase/ (6 source, 5 test)\n- 5,746 total lines of code\n- 84 passing tests with 69.8% coverage\n- Zero breaking changes\n\n**Features:**\n- CDP authentication with JWT signing\n- HTTP client with retry logic and error handling\n- Support for EVM (Base, Ethereum, Polygon) and SVM (Solana) networks\n- EIP-3009 and SPL Token TransferChecked signing\n- Automatic account creation and management\n- Multi-chain stateless design\n\n**Status:**\n✅ Phase 1-6: Core implementation complete\n✅ Phase 7: Error handling \u0026 retry logic\n✅ Phase 8: Multi-chain support validation\n✅ Phase 9: Polish and quality assurance\n✅ Committed and pushed to branch 006-cdp-signer\n✅ PR #10 created: https://github.com/mark3labs/x402-go/pull/10\n\n**Next Steps:**\n- Await PR review\n- Address any feedback\n- Merge to main","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-10-30T15:07:03.4494984+03:00","updated_at":"2025-10-30T15:07:14.321726793+03:00","closed_at":"2025-10-30T15:07:14.321726793+03:00","dependencies":[{"issue_id":"x402-go-19","depends_on_id":"x402-go-16","type":"discovered-from","created_at":"2025-10-30T15:07:03.459568291+03:00","created_by":"daemon"},{"issue_id":"x402-go-19","depends_on_id":"x402-go-17","type":"discovered-from","created_at":"2025-10-30T15:07:03.462047835+03:00","created_by":"daemon"},{"issue_id":"x402-go-19","depends_on_id":"x402-go-18","type":"discovered-from","created_at":"2025-10-30T15:07:03.464070914+03:00","created_by":"daemon"}]}
1212
{"id":"x402-go-2","title":"Error handling bug in handler.go sendPaymentRequiredWithRequirements","description":"","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-29T17:25:44.911411053+03:00","updated_at":"2025-10-29T17:30:51.891979853+03:00","closed_at":"2025-10-29T17:30:51.891979853+03:00"}
13-
{"id":"x402-go-20","title":"Add token address format validation for network type (EVM vs Solana)","description":"Add validation to ensure token addresses match the network type:\n- EVM networks (base, base-sepolia, polygon, etc.) should validate 0x-prefixed hex addresses (42 chars)\n- Solana networks (solana, solana-devnet) should validate base58 addresses (32-44 chars)\n\nThis prevents runtime errors like 'invalid base58 digit' when using EVM addresses on Solana networks.\n\nAffected components:\n- signers/coinbase/signer.go: WithToken() and WithTokenPriority() options\n- svm/signer.go: WithToken() and WithTokenPriority() options \n- evm/signer.go: WithToken() and WithTokenPriority() options\n\nImplementation:\n- Add helper function ValidateTokenAddress(network, address string) error\n- Call in signer option functions before appending to tokens list\n- Return descriptive error (e.g., 'token address 0x123... is invalid for Solana network, expected base58 format')\n\nDiscovered during CDP signer testing when EVM USDC address was used for solana-devnet.","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-30T16:53:00.227839944+03:00","updated_at":"2025-10-30T16:53:20.1556879+03:00"}
13+
{"id":"x402-go-20","title":"Add token address format validation for network type (EVM vs Solana)","description":"Add validation to ensure token addresses match the network type:\n- EVM networks (base, base-sepolia, polygon, etc.) should validate 0x-prefixed hex addresses (42 chars)\n- Solana networks (solana, solana-devnet) should validate base58 addresses (32-44 chars)\n\nThis prevents runtime errors like 'invalid base58 digit' when using EVM addresses on Solana networks.\n\nAffected components:\n- signers/coinbase/signer.go: WithToken() and WithTokenPriority() options\n- svm/signer.go: WithToken() and WithTokenPriority() options \n- evm/signer.go: WithToken() and WithTokenPriority() options\n\nImplementation:\n- Add helper function ValidateTokenAddress(network, address string) error\n- Call in signer option functions before appending to tokens list\n- Return descriptive error (e.g., 'token address 0x123... is invalid for Solana network, expected base58 format')\n\nDiscovered during CDP signer testing when EVM USDC address was used for solana-devnet.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-30T16:53:00.227839944+03:00","updated_at":"2025-10-31T15:01:36.504179742+03:00","closed_at":"2025-10-31T15:01:36.504179742+03:00"}
14+
{"id":"x402-go-21","title":"Phase 5 User Story 3 - Multi-Chain Payment Support","description":"","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-10-31T14:05:52.665980288+03:00","updated_at":"2025-10-31T14:17:49.251759651+03:00","closed_at":"2025-10-31T14:17:49.251759651+03:00"}
15+
{"id":"x402-go-22","title":"chains.go:305-306 - Redundant and incorrect 0x prefix validation logic","description":"The EVM address validation checks address[0:2] for '0x' prefix before checking with common.IsHexAddress(), creating redundant logic. An address of exactly '0x' could pass prefix check but fail validation. Fix: Remove redundant prefix check on lines 305-308 and rely solely on common.IsHexAddress().","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-10-31T16:46:12.900550271+03:00","updated_at":"2025-10-31T16:49:02.864196065+03:00","closed_at":"2025-10-31T16:49:02.864196065+03:00"}
16+
{"id":"x402-go-23","title":"chains.go:9-16 - Inconsistent import organization","description":"Imports don't follow project convention of grouping stdlib, external deps, then internal packages. The 'math' import is incorrectly grouped. Should follow pattern: fmt/strconv (stdlib), blank line, external deps.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-31T16:46:14.546511319+03:00","updated_at":"2025-10-31T16:49:17.986433932+03:00","closed_at":"2025-10-31T16:49:17.986433932+03:00"}
17+
{"id":"x402-go-24","title":"chains_test.go - Inconsistent error assertion patterns","description":"Tests use strings.Contains() for error validation (lines 842-844) instead of exact matching used elsewhere in same file (e.g., TestValidateNetworkUnknown at 715-716). Should standardize on exact error matching with wantError field or document why partial matching is needed.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-10-31T16:46:17.025750471+03:00","updated_at":"2025-10-31T16:50:45.782774693+03:00","closed_at":"2025-10-31T16:50:45.782774693+03:00"}
18+
{"id":"x402-go-25","title":"examples/mcp/main.go - Documentation-only example misleads users","description":"File structured as runnable example but only prints documentation text (lines 79-94). Every other example in /examples contains working executable code. Users expect working examples. Fix: Either create working MCP example, move to docs/, or rename to examples/mcp-docs/.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-31T16:46:19.186558442+03:00","updated_at":"2025-10-31T16:51:09.194412123+03:00","closed_at":"2025-10-31T16:51:09.194412123+03:00"}
19+
{"id":"x402-go-26","title":"examples/mcp/go.mod - Unnecessary dependencies in doc-only example","description":"Documentation-only example has full dependency tree (250 lines in go.sum). Creates false dependency signals and increases vulnerability surface. If keeping as docs-only, remove dependencies. If converting to working example, ensure code actually executes.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-31T16:46:21.005417751+03:00","updated_at":"2025-10-31T16:51:10.17373168+03:00","closed_at":"2025-10-31T16:51:10.17373168+03:00"}
20+
{"id":"x402-go-27","title":"mcp/client/transport.go:28-34 - Unsafe signer mutation violates encapsulation","description":"WithSigner() directly mutates unexported 'signers' field of PaymentHandler, violating encapsulation. No validation for duplicates. Fix: Add PaymentHandler.AddSigner() method and use it in WithSigner() option function.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-31T16:46:22.7442039+03:00","updated_at":"2025-10-31T16:51:39.378089264+03:00","closed_at":"2025-10-31T16:51:39.378089264+03:00"}
21+
{"id":"x402-go-28","title":"chains.go - Missing godoc examples for ValidateTokenAddress","description":"ValidateTokenAddress (lines 280-322) has comprehensive godoc but lacks usage examples that other exported functions have. Function is used by signers/evm, signers/svm, signers/coinbase. Add godoc examples showing EVM and Solana address validation.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-31T16:46:25.747985183+03:00","updated_at":"2025-10-31T16:53:18.19856762+03:00","closed_at":"2025-10-31T16:53:18.19856762+03:00"}
22+
{"id":"x402-go-29","title":"mcp/types.go:20-28 - Dead references to non-existent FR-017/FR-018 requirements","description":"Timeout constants reference (FR-017, FR-018) in comments but these requirement documents don't exist anywhere in specs/. Fix: Either remove FR references, add actual FR documents to specs/007-mcp-integration/, or inline explain the rationale.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-31T16:46:28.663414558+03:00","updated_at":"2025-10-31T16:53:38.921308791+03:00","closed_at":"2025-10-31T16:53:38.921308791+03:00"}
1423
{"id":"x402-go-3","title":"Potential case-sensitivity issue in token address matching","description":"","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-10-29T17:25:45.967861712+03:00","updated_at":"2025-10-29T20:14:39.09993865+03:00","closed_at":"2025-10-29T20:14:39.09993865+03:00"}
24+
{"id":"x402-go-30","title":"chains.go:304-311 - Redundant validation logic duplicates common.IsHexAddress","description":"Custom prefix check duplicates what common.IsHexAddress already validates. Adds ~40 lines of tests (chains_test.go:796-833) for delegated logic. Simplify by removing redundant prefix validation and relying on go-ethereum's implementation.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-31T16:46:30.423865728+03:00","updated_at":"2025-10-31T16:54:01.088058645+03:00","closed_at":"2025-10-31T16:54:01.088058645+03:00"}
25+
{"id":"x402-go-31","title":"mcp/server/middleware.go - Stub implementation with nolint suppressions indicates incomplete feature","description":"Entire file contains stub functions with //nolint:unused directives (lines 30, 60, 69, 85). TODO comments indicate placeholder code. Creates false confidence that MCP integration is complete. Fix: Remove from PR until complete, mark as Phase 2 in spec, or implement functions.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-31T16:46:32.709036069+03:00","updated_at":"2025-10-31T16:52:42.706897426+03:00","closed_at":"2025-10-31T16:52:42.706897426+03:00"}
26+
{"id":"x402-go-32","title":"chains_test.go - Missing package-level documentation","description":"938-line test file lacks package-level godoc explaining test organization. Should document test categories: ChainConfig constants, token configuration, payment requirements, network validation, token address validation.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-31T16:46:34.785464036+03:00","updated_at":"2025-10-31T16:54:18.313287896+03:00","closed_at":"2025-10-31T16:54:18.313287896+03:00"}
27+
{"id":"x402-go-33","title":"chains_test.go:739-764 - Missing EIP-55 checksum address test case","description":"Tests cover lowercase, uppercase, and zero addresses but don't explicitly test EIP-55 mixed-case checksum addresses (standard Ethereum format). Add labeled test case for checksummed addresses to ensure validation handles them correctly.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-31T16:46:37.040206508+03:00","updated_at":"2025-10-31T16:54:39.879193745+03:00","closed_at":"2025-10-31T16:54:39.879193745+03:00"}
28+
{"id":"x402-go-34","title":"Inconsistent project naming: x402-go vs X402","description":"Project name inconsistent across codebase. Module name uses 'x402-go' (hyphenated), types use 'X402' (no hyphen). Establish convention: Module/package: x402-go, Types/symbols: X402, Documentation: 'x402' protocol, 'x402-go' library.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-31T16:46:39.688234546+03:00","updated_at":"2025-10-31T16:55:08.941086168+03:00","closed_at":"2025-10-31T16:55:08.941086168+03:00"}
29+
{"id":"x402-go-35","title":"PR Review: 007-mcp-integration code quality issues","description":"Comprehensive code review findings for the 007-mcp-integration branch. This epic tracks all issues discovered during codebase analysis of the MCP integration PR. Issues grouped by severity: Critical (2), High (4), Medium (4), Low (3). Total: 13 issues requiring resolution before merge.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-10-31T16:46:45.91505186+03:00","updated_at":"2025-10-31T16:56:07.25012286+03:00","closed_at":"2025-10-31T16:56:07.25012286+03:00","dependencies":[{"issue_id":"x402-go-35","depends_on_id":"x402-go-22","type":"blocks","created_at":"2025-10-31T16:47:16.529158943+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-23","type":"blocks","created_at":"2025-10-31T16:47:16.539076219+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-24","type":"blocks","created_at":"2025-10-31T16:47:16.548628946+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-25","type":"blocks","created_at":"2025-10-31T16:47:16.559154332+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-26","type":"blocks","created_at":"2025-10-31T16:47:16.568433202+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-27","type":"blocks","created_at":"2025-10-31T16:47:16.578182491+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-28","type":"blocks","created_at":"2025-10-31T16:47:16.587342897+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-29","type":"blocks","created_at":"2025-10-31T16:47:17.978771982+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-30","type":"blocks","created_at":"2025-10-31T16:47:17.989289132+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-31","type":"blocks","created_at":"2025-10-31T16:47:18.000094085+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-32","type":"blocks","created_at":"2025-10-31T16:47:18.010327269+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-33","type":"blocks","created_at":"2025-10-31T16:47:18.019944578+03:00","created_by":"daemon"},{"issue_id":"x402-go-35","depends_on_id":"x402-go-34","type":"blocks","created_at":"2025-10-31T16:47:18.02830325+03:00","created_by":"daemon"}]}
1530
{"id":"x402-go-4","title":"DEBUG log statements should be removed or guarded by log level","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-29T17:25:52.122397206+03:00","updated_at":"2025-10-29T20:14:37.954623981+03:00","closed_at":"2025-10-29T20:14:37.954623981+03:00"}
1631
{"id":"x402-go-5","title":"http/handler.go sendPaymentRequired has error handling bug after headers sent","description":"","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-29T17:25:53.303006718+03:00","updated_at":"2025-10-29T17:30:51.694604235+03:00","closed_at":"2025-10-29T17:30:51.694604235+03:00"}
1732
{"id":"x402-go-6","title":"http/transport.go only uses first payment requirement, ignores others","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-29T17:25:54.586548474+03:00","updated_at":"2025-10-29T20:14:36.93246443+03:00","closed_at":"2025-10-29T20:14:36.93246443+03:00"}
1833
{"id":"x402-go-7","title":"selector.go token address comparison may be case-sensitive (inconsistent with CanSign)","description":"","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-29T17:25:55.754248706+03:00","updated_at":"2025-10-29T17:29:38.542544877+03:00","closed_at":"2025-10-29T17:29:38.542544877+03:00"}
1934
{"id":"x402-go-8","title":"evm/signer.go getChainID returns 0 for unknown networks (should error)","description":"","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-10-29T17:25:57.090133157+03:00","updated_at":"2025-10-29T17:30:50.968183492+03:00","closed_at":"2025-10-29T17:30:50.968183492+03:00"}
20-
{"id":"x402-go-9","title":"Missing test coverage for examples/ directory","description":"","status":"open","priority":3,"issue_type":"task","created_at":"2025-10-29T17:25:58.153980412+03:00","updated_at":"2025-10-29T17:25:58.153980412+03:00"}
35+
{"id":"x402-go-9","title":"Missing test coverage for examples/ directory","description":"","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-29T17:25:58.153980412+03:00","updated_at":"2025-10-31T15:04:06.176205527+03:00","closed_at":"2025-10-31T15:04:06.176205527+03:00"}

go.mod

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ require (
5757
github.com/klauspost/cpuid/v2 v2.2.7 // indirect
5858
github.com/leodido/go-urn v1.4.0 // indirect
5959
github.com/logrusorgru/aurora v2.0.3+incompatible // indirect
60+
github.com/mark3labs/mcp-go v0.42.0 // indirect
6061
github.com/mattn/go-colorable v0.1.14 // indirect
6162
github.com/mattn/go-isatty v0.0.20 // indirect
6263
github.com/mitchellh/go-testing-interface v1.14.1 // indirect

0 commit comments

Comments
 (0)