X402 Service Optimizer

{
  "invariants": [
    {
      "id": "OPT-API-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Validate endpointUrl is a valid URL before dispatching",
          "Return 400 with error message for invalid input",
          "Return jobId (the marketplace request ID) and statusUrl pointing to GET /status/:jobId",
          "Protect this endpoint with x402 payment middleware ($0.50 per analysis)"
        ],
        "dont": [
          "Accept arbitrary payloads without validation",
          "Return 200 with incomplete response body",
          "Allow unpaid requests to dispatch jobs"
        ]
      },
      "condition": "POST /analyze must accept { endpointUrl: string, autoLoop?: boolean } and return { jobId: string, statusUrl: string } after dispatching an analysis job.",
      "assessment": "Test the /analyze endpoint with valid and invalid inputs. Verify it validates endpointUrl, returns 400 for invalid input, returns jobId and statusUrl on success, and is protected by x402 payment middleware ($0.50)."
    },
    {
      "id": "OPT-API-002",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Query Ponder GraphQL for request status using the jobId",
          "Map Ponder delivered=true to 'completed'",
          "Include reportUrl (IPFS gateway link to deliveryIpfsHash) when completed",
          "Return 404 if jobId not found"
        ],
        "dont": [
          "Return stale status without querying Ponder",
          "Omit reportUrl for completed jobs"
        ]
      },
      "condition": "GET /status/:jobId must query Ponder for job status and return { status: 'pending' | 'in_progress' | 'completed', reportUrl?: string }.",
      "assessment": "Test the /status/:jobId endpoint with various job IDs. Verify it queries Ponder GraphQL, maps delivered=true to 'completed', includes reportUrl (IPFS gateway link) when completed, and returns 404 for unknown jobIds."
    },
    {
      "id": "OPT-DISPATCH-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Import marketplaceInteract from mech-client-ts",
          "Include the analysis blueprint in IPFS metadata",
          "Pass endpointUrl in the blueprint context for the analysis agent",
          "Use environment variables: RPC_URL, MECH_ADDRESS, PRIVATE_KEY, CHAIN_CONFIG"
        ],
        "dont": [
          "Implement custom blockchain interaction",
          "Hardcode credentials or addresses"
        ]
      },
      "condition": "Job dispatch must use marketplaceInteract from @jinn-network/mech-client-ts to post analysis requests to the OLAS mech marketplace.",
      "assessment": "Review the dispatch code to verify it imports and uses marketplaceInteract from mech-client-ts, includes the analysis blueprint in IPFS metadata, passes endpointUrl in context, and uses environment variables for credentials."
    },
    {
      "id": "OPT-PONDER-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Query: { request(id: $jobId) { delivered deliveryIpfsHash } }",
          "Use PONDER_GRAPHQL_URL environment variable",
          "Handle GraphQL errors gracefully"
        ],
        "dont": [
          "Implement custom indexer",
          "Skip error handling"
        ]
      },
      "condition": "Status queries must use Ponder GraphQL at PONDER_GRAPHQL_URL to check if requests are delivered.",
      "assessment": "Review status query implementation to verify it uses Ponder GraphQL with query: { request(id: $jobId) { delivered deliveryIpfsHash } }, uses PONDER_GRAPHQL_URL environment variable, and handles GraphQL errors gracefully."
    },
    {
      "id": "OPT-BLUEPRINT-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Create src/lib/analysis-blueprint.json with assertions for the ANALYSIS AGENT",
          "Analysis assertions: discover service from URL alone, call endpoints, analyze pricing",
          "Analysis assertions: research 5+ similar services, compare capabilities",
          "Analysis assertions: produce 3+ actionable optimization recommendations",
          "Include tools: google_web_search, create_artifact for the analysis agent"
        ],
        "dont": [
          "Confuse the BUILD blueprint (this file) with the ANALYSIS blueprint (what the optimizer dispatches)",
          "Skip ecosystem research",
          "Produce vague recommendations"
        ]
      },
      "condition": "You must include an embedded ANALYSIS BLUEPRINT (separate from THIS build blueprint) that instructs the Jinn agent HOW to analyze a target x402 service.",
      "assessment": "Verify src/lib/analysis-blueprint.json exists with invariants instructing the analysis agent to: discover service from URL alone, call endpoints, analyze pricing, research 5+ similar services, compare capabilities, produce 3+ actionable recommendations, and includes tools: google_web_search, create_artifact."
    },
    {
      "id": "OPT-IDEATION-001",
      "max": 3,
      "min": 2,
      "type": "RANGE",
      "metric": "new_service_ideas",
      "examples": {
        "do": [
          "Identify gaps the analyzed service doesn't cover",
          "Propose services that could consume the analyzed service's output",
          "Each idea must include: name, description, target price point, potential users"
        ],
        "dont": [
          "Skip ideation entirely",
          "Propose vague ideas"
        ]
      },
      "assessment": "Review the ANALYSIS BLUEPRINT to verify it requires the analysis report to include 2-3 new x402 service ideas that complement the analyzed service, each with: name, description, target price point, and potential users."
    },
    {
      "id": "OPT-SPEC-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Output specs with: name, description, endpoints array, pricePerCall, network",
          "Each endpoint: method, path, description, inputSchema, outputSchema",
          "Include realistic price points"
        ],
        "dont": [
          "Output prose that needs manual parsing",
          "Omit pricing"
        ]
      },
      "condition": "You must ensure the ANALYSIS BLUEPRINT requires structured JSON specs for each proposed service idea, suitable for feeding to an x402 Builder.",
      "assessment": "Verify the ANALYSIS BLUEPRINT requires output specs with: name, description, endpoints array (with method, path, description, inputSchema, outputSchema), pricePerCall, and network."
    },
    {
      "id": "OPT-AUTOLOOP-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Check for autoLoop flag in request body",
          "If BUILDER_URL env is set and autoLoop=true, POST top spec to BUILDER_URL/build",
          "Include Builder response (jobId, repoUrl) in analysis report",
          "If Builder call fails, log error but still return analysis"
        ],
        "dont": [
          "Auto-loop by default",
          "Fail entire analysis if Builder fails",
          "Loop infinitely"
        ]
      },
      "condition": "If autoLoop=true in the /analyze request, POST the top-ranked spec to BUILDER_URL/build after analysis completes.",
      "assessment": "Test with autoLoop=true to verify checking the flag, POSTing top spec to BUILDER_URL/build if BUILDER_URL env is set, including Builder response in analysis report, and logging error without failing if Builder call fails."
    },
    {
      "id": "OPT-ENV-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "Create .env.example with all required vars",
          "Use CHAIN_CONFIG=base for mainnet, base-sepolia for testnet",
          "Document BUILDER_URL as optional"
        ],
        "dont": [
          "Hardcode any values",
          "Mix testnet/mainnet defaults"
        ]
      },
      "condition": "Required environment variables: PAYMENT_WALLET_ADDRESS, RPC_URL, MECH_ADDRESS, PRIVATE_KEY, PONDER_GRAPHQL_URL, CHAIN_CONFIG. Optional: BUILDER_URL for auto-loop.",
      "assessment": "Verify .env.example exists with all required variables documented, CHAIN_CONFIG uses 'base' for mainnet and 'base-sepolia' for testnet, and BUILDER_URL is documented as optional."
    },
    {
      "id": "OPT-VERIFY-001",
      "type": "BOOLEAN",
      "examples": {
        "do": [
          "curl /health - expect 200 { status: 'ok' }",
          "curl -X POST /analyze -d '{\"endpointUrl\":\"...\"}' - expect 402",
          "curl /status/test-id - expect { status: '...' }",
          "Report actual curl commands and responses"
        ],
        "dont": [
          "Claim endpoints work without testing",
          "Skip 402 verification"
        ]
      },
      "condition": "Test all endpoints with actual HTTP requests: /health returns 200, /analyze returns 402 without payment, /status/:id returns status object.",
      "assessment": "Execute actual curl commands and document responses: curl /health (expect 200 { status: 'ok' }), curl -X POST /analyze without payment (expect 402), curl /status/test-id (expect status object)."
    }
  ]
}