You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/brainstorms/atlantic-bun-sdk-requirements.md
+5Lines changed: 5 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -63,6 +63,7 @@ The SDK should make Atlantic easier to use from Bun and TypeScript projects with
63
63
## Requirements
64
64
65
65
**API coverage**
66
+
66
67
- R1. The SDK must expose typed methods for every public Atlantic API capability documented in the current Atlantic OpenAPI contract: health check, submit query, get query by ID, get query by dedup ID, list queries, query stats, query jobs, retry query, list buckets, create bucket, get bucket details, and close bucket.
67
68
- R2. Query submission must support the documented Atlantic inputs and options, including program, input, PIE, and proof file inputs; Cairo version and VM options; result selection; layouts; prover selection; declared job size; network selection; deduplication identifiers; external identifiers; and bucket-related fields.
68
69
- R3. Query lookup must support direct query ID lookup and deduplication-key lookup as separate explicit capabilities.
@@ -72,24 +73,28 @@ The SDK should make Atlantic easier to use from Bun and TypeScript projects with
72
73
- R7. Bucket support must cover listing buckets, creating buckets, fetching bucket details with associated queries, closing buckets, and submitting bucket-linked queries where the API permits them.
73
74
74
75
**Agent-first workflow helpers**
76
+
75
77
- R8. The SDK must include higher-level helpers for common workflows: submit-and-return-ID, submit-and-wait, wait-for-query, retry-if-retriable, get-query-with-jobs, and bucket-oriented submission.
76
78
- R9. Workflow helpers must preserve caller control over polling intervals, timeout budgets, retry budgets, and terminal-state behavior.
77
79
- R10. The SDK must keep Atlantic query IDs, dedup IDs, and bucket IDs visible as first-class outputs rather than hiding them inside opaque workflow results.
78
80
- R11. Agent-facing helper descriptions must include what the helper does, when to use it, required inputs, important constraints, expected result, and common failure modes.
79
81
80
82
**x402 payments**
83
+
81
84
- R12. The SDK must support Atlantic's documented x402 v2 flow for `submit query`, including challenge parsing, payment-signature retry, and settlement-response parsing.
82
85
- R13. The SDK must support both API-key fallback payments and anonymous wallet payments, while making their behavioral differences explicit to the caller.
83
86
- R14. The SDK must prevent or clearly warn against unsafe x402 usage: preemptive payment signatures, reused successful payment signatures, hardcoded payment requirements, anonymous `dedupId` usage, anonymous bucket usage, and double-payment after ambiguous settlement.
84
87
- R15. x402 signing must be wallet-adapter friendly so applications can provide their own signing implementation rather than coupling the SDK to a single wallet source.
85
88
86
89
**CLI**
90
+
87
91
- R16. The CLI must expose commands for the same main capabilities as the SDK: submit query, retry query, get query details, get query by dedup ID, list queries, get query jobs, query stats, list buckets, create bucket, get bucket, close bucket, and health check.
88
92
- R17. CLI commands must support file-path inputs for query submission and must print machine-readable JSON by default or through an explicit mode.
89
93
- R18. CLI commands must support environment-based configuration for the Atlantic base URL, API key, and payment-related wallet configuration.
90
94
- R19. CLI output must preserve important identifiers, status, payment receipt data, and error details so agents can chain commands reliably.
91
95
92
96
**Developer experience and quality**
97
+
93
98
- R20. The package must be Bun-first while remaining idiomatic TypeScript for library consumers.
94
99
- R21. Public SDK methods must have clear names, strong TypeScript types, and documentation comments that explain behavior rather than merely restating parameter names.
95
100
- R22. The SDK must separate low-level API methods from higher-level workflow helpers so advanced users can keep exact control while agents and common integrations get safer defaults.
0 commit comments