|
| 1 | +# Solana AI Registries – **SDK Master Plan** |
| 2 | +*(coverage = 100 % on-chain instructions + 100 % payment flows)* |
| 3 | + |
| 4 | +--- |
| 5 | + |
| 6 | +## 0. Common Artifacts (central repo = `sdk-assets`) |
| 7 | +* `idl/agent_registry.json` – Anchor IDL (v1 hash: `b6e4…`) |
| 8 | +* `idl/mcp_server_registry.json` – Anchor IDL (v1 hash: `c1fd…`) |
| 9 | +* `idl/svmai_token.json` – SPL-mint interface |
| 10 | +* `schemas/payment-metadata.schema.json` – strict JSON Schema (draft-2020-12) |
| 11 | +* `fixtures/` |
| 12 | + * `agent-card.valid.json` / `agent-card.invalid.json` |
| 13 | + * `mcp-card.valid.json` / `mcp-card.invalid.json` |
| 14 | + * `pricing-metadata.valid.json` |
| 15 | +* CI job `verify-idl-hash` → blocks merge if IDL hash drift detected. |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## 1. **Rust crate** `solana_ai_registries` |
| 20 | +### 1.1 Crate layout (`src/`) |
| 21 | +| File | Purpose | |
| 22 | +| ---- | ------- | |
| 23 | +| `lib.rs` | re-exports + feature gates | |
| 24 | +| `agent/mod.rs` | high-level builder, typed requests | |
| 25 | +| `mcp/mod.rs` | same for servers | |
| 26 | +| `payments/mod.rs` | three flow engines | |
| 27 | +| `client.rs` | wrapper around `solana_client::rpc_client::RpcClient` | |
| 28 | +| `errors.rs` | `#[error_code]` mirrored enums | |
| 29 | +| `idl.rs` | compile-time inclusion of JSON IDLs | |
| 30 | + |
| 31 | +### 1.2 Public API (excerpt) |
| 32 | +```rust |
| 33 | +pub fn register_agent(cx: &Signer, args: AgentArgs) -> Result<Signature>; |
| 34 | +pub fn update_agent(cx: &Signer, id: &str, patch: AgentPatch) -> Result<Signature>; |
| 35 | +pub fn pay_pyg(cx: &Signer, mint: Pubkey, lamports: u64, treasury: Pubkey) -> Result<Signature>; |
| 36 | +``` |
| 37 | + |
| 38 | +### 1.3 Tests |
| 39 | +* `tests/agent_flow.rs` – covers full CRUD, 26 cases. |
| 40 | +* `tests/payment_pyg.rs` – CU budget + balance assertions. |
| 41 | +* Snapshot tests against devnet ledger replay (`ledger/devnet/`). |
| 42 | + |
| 43 | +### 1.4 Release |
| 44 | +* Feature flags: `stream`, `pyg`, `prepay`. |
| 45 | +* `cargo publish` gated by `cargo deny` and MSRV 1.74. |
| 46 | + |
| 47 | +--- |
| 48 | + |
| 49 | +## 2. **TypeScript package** `@svmai/registries` |
| 50 | +### 2.1 Directory tree |
| 51 | +``` |
| 52 | +src/ |
| 53 | + agent.ts // AgentAPI class |
| 54 | + mcp.ts // MCPAPI class |
| 55 | + payments/ |
| 56 | + prepay.ts |
| 57 | + pyg.ts |
| 58 | + stream.ts |
| 59 | + utils/ |
| 60 | + idl.ts // cached IDL loader |
| 61 | + borsh.ts // Borsh helpers |
| 62 | +examples/ |
| 63 | + register-agent.ts |
| 64 | + update-server.ts |
| 65 | + pay-pyg.ts |
| 66 | +``` |
| 67 | +### 2.2 Key functions |
| 68 | +```ts |
| 69 | +registerAgent(connection, signer, card: AgentCard): Promise<string>; |
| 70 | +payAsYouGo(connection, signer, cfg: PayCfg): Promise<string>; |
| 71 | +``` |
| 72 | +### 2.3 Tooling |
| 73 | +* Built with TS 5.5, target ES2022. |
| 74 | +* Strict ESM + type exports. |
| 75 | +* Jest + `@solana/web3.js` local validator fixture. |
| 76 | +* `npm run docs` → typedoc. |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +## 3. **Go module** `github.com/svmai/registries` |
| 81 | +### 3.1 Packages |
| 82 | +* `client` – RPC + Tx builder |
| 83 | +* `agent` / `mcp` – high-level ops |
| 84 | +* `payments` – flow implementations |
| 85 | +* `idl` – generated `go:embed` structs |
| 86 | + |
| 87 | +### 3.2 Example |
| 88 | +```go |
| 89 | +agent.Register(ctx, rpc, signer, agent.Card{ID:"bot-1", …}) |
| 90 | +payments.PayPYG(ctx, rpc, signer, payments.Config{Mint: svmaiMint, …}) |
| 91 | +``` |
| 92 | +### 3.3 QA |
| 93 | +`go test ./... -run TestIntegration -tags=devnet` |
| 94 | + |
| 95 | +--- |
| 96 | + |
| 97 | +## 4. **Python package** `svmai-registries` |
| 98 | +### 4.1 Modules |
| 99 | +* `ai_registries.agent` / `ai_registries.mcp` |
| 100 | +* `ai_registries.payments` (async) |
| 101 | +* `ai_registries.idl` – lazy-loaded via `anchorpy.Idl`. |
| 102 | + |
| 103 | +### 4.2 API surfaces |
| 104 | +```python |
| 105 | +sig = await Agent.register(agent_card, payer, client) |
| 106 | +await Payments.pay_pyg(amount=1_000_000, mint=SVMAI_MINT, payer=payer) |
| 107 | +``` |
| 108 | +### 4.3 Docs |
| 109 | +* Sphinx → RTD publish. |
| 110 | +* Jupyter notebooks under `examples/`. |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## 5. **C SDK** `libaireg` |
| 115 | +### 5.1 Files |
| 116 | +``` |
| 117 | +include/aireg.h // 62 exported funcs |
| 118 | +src/agent.c |
| 119 | +src/mcp.c |
| 120 | +src/payments.c |
| 121 | +bindings/solana/ // from anchor-gen |
| 122 | +examples/register.c |
| 123 | +``` |
| 124 | +### 5.2 Build |
| 125 | +```bash |
| 126 | +cmake -B build && cmake --build build |
| 127 | +``` |
| 128 | +### 5.3 ABI |
| 129 | +* Follows `solana-c` account structs; all pointers validated; returns `AI_ERR_*` codes. |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +## 6. **C++17 wrapper** `aireg++` |
| 134 | +* Header-only `aireg.hpp`, uses namespaces and RAII. |
| 135 | +* Bridges to `libaireg` via `extern "C"`. |
| 136 | + |
| 137 | +--- |
| 138 | + |
| 139 | +## 7. Payment Flow Support (matrix) |
| 140 | + |
| 141 | +| SDK | Pre-pay | Pay-as-you-go | Stream (Lights.so) | |
| 142 | +|-----|---------|--------------|--------------------| |
| 143 | +| Rust | ✓ `payments::prepay` | ✓ `payments::pyg` | ✓ feature `stream` | |
| 144 | +| TS | ✓ | ✓ | ✓ | |
| 145 | +| Go | ✓ | ✓ | ✓ via interface | |
| 146 | +| Py | ✓ | ✓ | ✓ (async tasks) | |
| 147 | +| C | ✓ | ✓ | ✗ (planned Q3) | |
| 148 | +| C++ | ✓ | ✓ | ✗ (inherits C) | |
| 149 | + |
| 150 | +--- |
| 151 | + |
| 152 | +## 8. Example Scenario Walkthrough (`demos/e2e/`) |
| 153 | +1. `01_mint_svmai.sh` → creates mint + treasury ATA. |
| 154 | +2. `02_register_mcp.<lang>` → register server, attach `pricing-metadata.json` (Arweave upload script). |
| 155 | +3. `03_client_pay_and_call.<lang>` → perform PYG payment, then HTTP RPC call, then parse JSON response. |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## 9. Milestones (calendar-week granularity) |
| 160 | + |
| 161 | +| Week | Deliverable | Owner | Exit Criteria | |
| 162 | +|------|-------------|-------|---------------| |
| 163 | +| 24-25 | Rust core + tests | Core team | 100 % instruction coverage | |
| 164 | +| 25-26 | TS parity | Frontend | npm v0.1 published | |
| 165 | +| 26-27 | Python + Go autogen | SDK guild | devnet demo passes | |
| 166 | +| 27-28 | C base + C++ wrapper | Systems | CI on Ubuntu + macOS | |
| 167 | +| 29 | Cross-lang e2e + docs | Docs squad | All demos succeed on CI | |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +## 10. CI Matrix (`.github/workflows/sdk.yml`) |
| 172 | +* Linux & macOS runners |
| 173 | +* Job 1 Rust → `cargo test --all --features stream` |
| 174 | +* Job 2 Node 20 → `npm test` |
| 175 | +* Job 3 Go 1.22 → `go test ./...` |
| 176 | +* Job 4 Python 3.12 → `pytest` |
| 177 | +* Job 5 C/C++ → `cmake --build` + `ctest` |
| 178 | +* Job 6 E2E devnet spin-up → shell scripts execute demos in all languages. |
| 179 | + |
| 180 | +--- |
| 181 | +## 11. GitHub Actions – *Package-manager Publishing* |
| 182 | + |
| 183 | +```yaml |
| 184 | +# .github/workflows/publish.yml |
| 185 | +name: Publish SDKs |
| 186 | + |
| 187 | +on: |
| 188 | + push: |
| 189 | + tags: |
| 190 | + - 'sdk/**' # e.g. sdk/ts/v0.1.2, sdk/rust/v1.0.0 … |
| 191 | + |
| 192 | +permissions: |
| 193 | + contents: read |
| 194 | + id-token: write # OIDC for crates.io / PyPI / npm / etc. |
| 195 | + |
| 196 | +jobs: |
| 197 | + # ───────────────────────────────────────── Rust ───────────────────────────────────────── |
| 198 | + rust-crate: |
| 199 | + if: startsWith(github.ref, 'refs/tags/sdk/rust/') |
| 200 | + runs-on: ubuntu-latest |
| 201 | + defaults: { run: { working-directory: rust } } |
| 202 | + steps: |
| 203 | + - uses: actions/checkout@v4 |
| 204 | + - uses: dtolnay/rust-toolchain@stable |
| 205 | + - run: cargo publish --token ${{ secrets.CARGO_TOKEN }} |
| 206 | + |
| 207 | + # ─────────────────────────────────── TypeScript / npm ─────────────────────────────────── |
| 208 | + node-package: |
| 209 | + if: startsWith(github.ref, 'refs/tags/sdk/ts/') |
| 210 | + runs-on: ubuntu-latest |
| 211 | + defaults: { run: { working-directory: typescript } } |
| 212 | + steps: |
| 213 | + - uses: actions/checkout@v4 |
| 214 | + - uses: actions/setup-node@v4 |
| 215 | + with: |
| 216 | + registry-url: 'https://registry.npmjs.org' |
| 217 | + node-version: '20' |
| 218 | + - run: npm ci |
| 219 | + - run: npm publish --access public |
| 220 | + env: |
| 221 | + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} |
| 222 | + |
| 223 | + # ───────────────────────────────────────── Go / goproxy ───────────────────────────────── |
| 224 | + go-module: |
| 225 | + if: startsWith(github.ref, 'refs/tags/sdk/go/') |
| 226 | + runs-on: ubuntu-latest |
| 227 | + defaults: { run: { working-directory: go } } |
| 228 | + steps: |
| 229 | + - uses: actions/checkout@v4 |
| 230 | + - run: go test ./... |
| 231 | + - name: Create version tag for Go proxy |
| 232 | + run: git tag $(echo $GITHUB_REF | cut -d'/' -f4) && git push --tags |
| 233 | + |
| 234 | + # ───────────────────────────────────────── Python / PyPI ──────────────────────────────── |
| 235 | + python-package: |
| 236 | + if: startsWith(github.ref, 'refs/tags/sdk/py/') |
| 237 | + runs-on: ubuntu-latest |
| 238 | + defaults: { run: { working-directory: python } } |
| 239 | + steps: |
| 240 | + - uses: actions/checkout@v4 |
| 241 | + - uses: actions/setup-python@v5 |
| 242 | + with: { python-version: '3.12' } |
| 243 | + - run: pip install build |
| 244 | + - run: python -m build |
| 245 | + - uses: pypa/gh-action-pypi-publish@release/v1 |
| 246 | + with: |
| 247 | + api-token: ${{ secrets.PYPI_TOKEN }} |
| 248 | + |
| 249 | + # ───────────────────────────────────────── C / C++ artefacts ──────────────────────────── |
| 250 | + c-binaries: |
| 251 | + if: startsWith(github.ref, 'refs/tags/sdk/c/') |
| 252 | + runs-on: ubuntu-latest |
| 253 | + defaults: { run: { working-directory: c } } |
| 254 | + steps: |
| 255 | + - uses: actions/checkout@v4 |
| 256 | + - run: cmake -B build && cmake --build build --target package |
| 257 | + - uses: softprops/action-gh-release@v1 |
| 258 | + with: |
| 259 | + files: build/*.tar.gz |
| 260 | + |
| 261 | + cpp-binaries: |
| 262 | + if: startsWith(github.ref, 'refs/tags/sdk/cpp/') |
| 263 | + runs-on: ubuntu-latest |
| 264 | + defaults: { run: { working-directory: cpp } } |
| 265 | + steps: |
| 266 | + - uses: actions/checkout@v4 |
| 267 | + - run: cmake -B build && cmake --build build --target package |
| 268 | + - uses: softprops/action-gh-release@v1 |
| 269 | + with: |
| 270 | + files: build/*.tar.gz |
| 271 | +``` |
| 272 | +
|
| 273 | +**Tag convention** |
| 274 | +
|
| 275 | +| SDK | Tag prefix example | |
| 276 | +| --- | ------------------ | |
| 277 | +| Rust | `sdk/rust/v1.0.0` | |
| 278 | +| TypeScript | `sdk/ts/v0.3.1` | |
| 279 | +| Go | `sdk/go/v1.2.0` | |
| 280 | +| Python | `sdk/py/v0.2.4` | |
| 281 | +| C | `sdk/c/v0.1.0` | |
| 282 | +| C++ | `sdk/cpp/v0.1.0` | |
| 283 | + |
| 284 | +Each job is gated by prefix match and publishes to the corresponding ecosystem using OIDC-based secrets (`CARGO_TOKEN`, `NPM_TOKEN`, `PYPI_TOKEN`). |
0 commit comments