tollbooth-dpyc.com

Good Earth — region-scoped climate analytics for small specialty-crop and flower farms, monetized via Tollbooth DPYC Bitcoin Lightning micropayments. ## The block is the point A farm is not a pin. Ground is saved once as a BLOCK — a polygon or a pin, with a name — and every tool then takes that block by its id, its name or an alias. Geometry travels once, not on every call. Each tool samples the terrain inside the block and reports an aggregate PLUS the spread across it, because a bench and a hollow on the same acreage do not share a frost date. Blocks may OVERLAP or NEST — a meadow drawn inside the farm around it, one bed inside a field, a trial strip across two. That is intended: a block is a question about some ground, not a parcel on a survey, so an overlap is two honest questions and never a drawing error. Do not report one as a mistake or offer to redraw it. Name a block loosely. Its id, its name, an alias, or any part of its name that only one block has all work — "Meadow" finds "Lower Meadow", and a saved "North Farm (east parcel)" answers to "North Farm". When several blocks match, the error names every one with its id, so choose from that list rather than adding an alias to get past it. Start with goodearth_block_list. If the grower has saved nothing it answers with a worked example, so there is always ground to stand on; save theirs with goodearth_block_save and it takes over. What they grow, watch for and have seen is recorded per block with goodearth_block_item_save, which is why the season tools need no collections passed to them. ## First connection, for a grower's agent 1. Ask the grower for their Nostr npub (npub1…). Never ask for an nsec. 2. goodearth_request_npub_proof(patron_npub=…) sends them a Nostr DM. Tell them to reply to it from their Nostr client, then call goodearth_receive_npub_proof(patron_npub=…, dpop_token=…) once. Pass npub and dpop_token on every paid call after that. 3. goodearth_check_balance. If it is empty, goodearth_purchase_credits returns a Lightning invoice for the grower to pay, and goodearth_check_payment confirms it. 4. goodearth_block_list — their saved ground, or a worked example. Needing none of that: goodearth_service_status and the goodearth_oracle_* tools. goodearth_check_price previews a fare. The same tools drive the web app at https://goodearth.tollbooth-dpyc.com. ## Operator onboarding For the operator of this service, not a grower. Call goodearth_get_operator_onboarding_status to check readiness. 1. Register with an Authority (provides a Neon database automatically) 2. Deliver operator secrets via Secure Courier: - btcpay_host, btcpay_api_key, btcpay_store_id Call goodearth_request_credential_channel to start. ## Pricing Tool prices are set dynamically by the operator's pricing model. Use `goodearth_check_price` to preview costs and `goodearth_check_balance` to see your balance. ## Troubleshooting Tool Failures When a tool call fails, **read the error message** — it tells you what went wrong and what to do next. Common causes: - **proof is required** → Call `request_npub_proof` then `receive_npub_proof` to prove npub ownership. The cache expires after ~1 hour; renew with a fresh request/receive cycle. - **Insufficient credit balance** → Call `purchase_credits` to top up. - **Operator credentials not delivered yet** → This is a lifecycle state, not an error. The operator needs to deliver API credentials via Secure Courier. Do NOT tell the patron to 'fix the deployment' or 'inject environment variables' — credential delivery is a Secure Courier flow, not a platform configuration issue. - **Service unavailable / persistence layer unreachable / only bootstrap tools** → The MCP is warming up after idle (serverless cold start). This is normal — retry in 10-15 seconds. Do NOT diagnose as an infrastructure outage or suggest the operator check their deployment. The second request almost always succeeds. - **Upstream API authentication failure** → Only if the error explicitly mentions token expiry or an upstream auth error. **IMPORTANT — Don't Pester Your Customer:** Do NOT ask the patron to re-authenticate, re-authorize, or re-do OAuth unless the error message specifically says the upstream token is expired or invalid. Token expiry is only one of many possible causes. Speculatively re-running OAuth or credential flows wastes the patron's time and is the opposite of what DPYC stands for. ## Secure Courier — Human in the Loop All Secure Courier flows (`request_credential_channel` / `receive_credentials`, `request_npub_proof` / `receive_npub_proof`) require a human to read a Nostr DM and reply manually. After calling a `request_*` tool, **STOP and wait** for the user to confirm they have replied. Do NOT poll, retry, or speculatively call `receive_*` — each receive call **destructively drains** all DMs from the relay. If you call it before the human replies, their message will be lost. One request, one wait, one receive.