nirium 0.16.0 → 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +82 -26
  2. package/package.json +4 -3
package/README.md CHANGED
@@ -28,7 +28,7 @@ console.log('Agent alive:', alive);
28
28
  const market = await agent.getMarket();
29
29
  console.log('XLM Price:', market.xlmPrice);
30
30
 
31
- // Trigger a demo strategy on Nirium's own shared testnet vault — a real,
31
+ // Trigger a demo strategy on Nirium's own shared testnet vault - a real,
32
32
  // working transaction, not a simulation, but it moves Nirium's testnet
33
33
  // funds, not yours. To rebalance YOUR OWN vault, see Treasury Rebalance below.
34
34
  const result = await agent.execute('blend-yield', 'USDC', { amount: 5000 });
@@ -82,7 +82,7 @@ const agent = new Agent({
82
82
 
83
83
  ## Payment Protocols
84
84
 
85
- ### x402 — Pay-Per-Request
85
+ ### x402: Pay-Per-Request
86
86
  ```typescript
87
87
  agent.initX402({
88
88
  secretKey: 'S...', // Stellar secret key
@@ -171,7 +171,7 @@ const response = await agent.mppFetch('https://your-mpp-server.example/resource'
171
171
  - In `push` mode the payment settles on-chain before the server verifies it, so a request the server rejects is **not refunded**.
172
172
  - Until this is diagnosed, use x402 (`initX402()`) for paid endpoints. The `get_mpp_*` tools of the MCP server have the same limitation.
173
173
 
174
- ### x402Serve() — Charging Your Own API
174
+ ### x402Serve(): Charging Your Own API
175
175
 
176
176
  `initX402()` above lets you *pay* for someone else's API. This is the other side: charging for yours.
177
177
 
@@ -179,19 +179,77 @@ const response = await agent.mppFetch('https://your-mpp-server.example/resource'
179
179
  import { x402Serve } from 'nirium';
180
180
 
181
181
  app.use('/premium', x402Serve({
182
- payTo: 'G...', // your Stellar address — where payments land
182
+ payTo: 'G...', // your Stellar address - where payments land
183
183
  routes: { 'GET /signals': '$0.02' },
184
184
  facilitatorApiKey: '...', // required on mainnet; OpenZeppelin Channels by default
185
185
  }));
186
186
  ```
187
187
 
188
- Runs on **your own server**, not Nirium's — `x402Serve()` is a client-side function you call from your own code; Nirium doesn't operate, host, or route through anything here, is never in the payment path, and never sees your end users' requests.
188
+ Runs on **your own server**, not Nirium's - `x402Serve()` is a client-side function you call from your own code; Nirium doesn't operate, host, or route through anything here, is never in the payment path, and never sees your end users' requests.
189
189
 
190
- **Known limitation:** `x402Serve()` verifies and settles the payment; it does not deduplicate a payment proof across requests or rate-limit callers on its own. Add your own protection if you need either - see [issue #91](https://github.com/nirium-protocol/nirium/issues/91) for what's missing, why, and a real production reference implementation.
190
+ **Known limitation:** by default `x402Serve()` does not protect against replay and does not rate-limit callers. It is turned on by passing `guard` (see below).
191
191
 
192
- **Usage telemetry — opt-in, off by default:** set `NIRIUM_X402SERVE_TELEMETRY=true` to send a small, non-blocking usage ping to Nirium — your `payTo` address, a SHA-256 hash of your `facilitatorApiKey` (never the key itself), network, route/request counts, and this SDK's version. It never blocks, delays, or fails a payment if the ping fails, times out, or isn't sent at all. Disabled by default since v0.14.0 — it's the only channel that would otherwise connect Nirium to how a specific integrator is using this locally-run function, and that isn't a decision this package should make for you.
192
+ #### Replay and rate-limit guard (optional)
193
193
 
194
- **Compliance is yours.** `x402Serve()` is a general-purpose library, not a service Nirium provides to your end users. You choose what to charge for, who your `payTo` is, and which jurisdiction you operate in — you remain solely responsible for complying with the financial, tax, and consumer-protection laws that apply to your own use of it.
194
+ Without `guard`, `x402Serve()` verifies and settles the payment and does nothing else. It does not stop the same signed payment from being sent twice, and it does not limit how often one caller can hit a route. Pass `guard` to get both:
195
+
196
+ - **Replay guard:** each payment proof can be used once per method and route (`replayTtlMs`, 15 minutes by default). A second use gets `409 payment_replayed`. If the request does not end in a 2xx, the claim is released, so a normal retry still works. If the store is down, the replay check refuses the request (`503`) instead of letting it through.
197
+ - **Rate limit:** optional, per caller IP (`req.ip`; set Express `trust proxy` if you run behind a proxy). Past `max` requests in `windowMs` the caller gets `429 rate_limited` with a `Retry-After` header. If the store is down, rate limiting lets traffic through.
198
+
199
+ The guard needs a store with three methods (`X402GuardStore`: `claimOnce`, `release`, `slidingWindowHit`). Two options:
200
+
201
+ ```typescript
202
+ import { x402Serve, createUpstashX402GuardStore, type X402GuardStore } from 'nirium';
203
+
204
+ // Option 1: Upstash (Redis over REST). Shared between several servers.
205
+ const store = createUpstashX402GuardStore({
206
+ url: process.env.UPSTASH_REDIS_REST_URL!,
207
+ token: process.env.UPSTASH_REDIS_REST_TOKEN!,
208
+ });
209
+
210
+ // Option 2: your own store. This one lives in memory, so it only works for a
211
+ // single process. For more than one server, back the same three methods with a shared store.
212
+ function createMemoryGuardStore(): X402GuardStore {
213
+ const claims = new Map<string, number>(); // key -> expires at
214
+ const hits = new Map<string, { t: number; member: string }[]>();
215
+ return {
216
+ async claimOnce(key, ttlMs) {
217
+ const now = Date.now();
218
+ if ((claims.get(key) ?? 0) > now) return false;
219
+ claims.set(key, now + ttlMs);
220
+ return true;
221
+ },
222
+ async release(key) { claims.delete(key); },
223
+ async slidingWindowHit(key, windowMs, member) {
224
+ const now = Date.now();
225
+ const list = (hits.get(key) ?? []).filter((h) => h.t > now - windowMs);
226
+ list.push({ t: now, member });
227
+ hits.set(key, list);
228
+ return list.length;
229
+ },
230
+ };
231
+ }
232
+
233
+ app.use('/premium', x402Serve({
234
+ payTo: 'G...',
235
+ routes: { 'GET /signals': '$0.02' },
236
+ facilitatorApiKey: '...',
237
+ guard: {
238
+ store, // or createMemoryGuardStore()
239
+ rateLimit: { max: 60, windowMs: 60_000 }, // optional
240
+ },
241
+ }));
242
+ ```
243
+
244
+ No in-memory store ships with the package, and you do not need Upstash: any store that implements the three methods works. The design comes from a real production integration by Edgadafi ([Edgadafi/remesa-liquidez](https://github.com/Edgadafi/remesa-liquidez)); see [issue #91](https://github.com/nirium-protocol/nirium/issues/91). The code here is ours. Thanks, Edgadafi.
245
+
246
+ **Usage telemetry - opt-in, off by default:** set `NIRIUM_X402SERVE_TELEMETRY=true` to send a small, non-blocking usage ping to Nirium - your `payTo` address, a SHA-256 hash of your `facilitatorApiKey` (never the key itself), network, route/request counts, and this SDK's version. It never blocks, delays, or fails a payment if the ping fails, times out, or isn't sent at all. Disabled by default since v0.14.0 - it's the only channel that would otherwise connect Nirium to how a specific integrator is using this locally-run function, and that isn't a decision this package should make for you.
247
+
248
+ **Compliance is yours.** `x402Serve()` is a general-purpose library, not a service Nirium provides to your end users. You choose what to charge for, who your `payTo` is, and which jurisdiction you operate in - you remain solely responsible for complying with the financial, tax, and consumer-protection laws that apply to your own use of it.
249
+
250
+ ### Resilient WebSocket client
251
+
252
+ `ResilientSignalClient` is a WebSocket client for `/ws/signals` that reconnects by itself with backoff, pings to detect dead connections, and drops duplicate signals. Create it with `{ url, token }`, call `connect()`, and listen with `onSignal()`, `onStatus()` and `onError()`; `close()` stops it.
195
253
 
196
254
  ### Endpoint Access Model
197
255
 
@@ -199,13 +257,13 @@ Runs on **your own server**, not Nirium's — `x402Serve()` is a client-side fun
199
257
  |---|---|
200
258
  | **Public** (no key) | `health`, `loop/status`, `execute-demo`, `signals/recent`, `skills` list |
201
259
  | **Protected** (API key) | `execute`, `market`, `loop/start\|stop\|scan`, `subscriptions`, `skills/install`, `webhooks` |
202
- | **WebSocket** (JWT) | `/ws/signals` — real-time signal stream |
203
- | **x402 Premium** | `/api/v1/premium/signals` ($0.02 USDC), `/api/v1/premium/market` ($0.05 USDC) |
260
+ | **WebSocket** (JWT) | `/ws/signals` - real-time signal stream |
261
+ | **x402 Premium** | `/api/v1/premium/signals` ($0.02 USDC), `/api/v1/premium/market` ($0.05 USDC). `/premium/signals` only exists on testnet: on mainnet it answers `501` (no signal source there) and does not charge. `/premium/market` is paid on both networks. |
204
262
  | **MPP Charge** | `/api/v1/mpp/signals`, `/api/v1/mpp/market` (testnet endpoint rejected MPP payments when tested, mainnet untested, see [MPP Charge](#mpp-charge-experimental)) |
205
263
 
206
- ### x402 Metrics — Observability Wrapper
264
+ ### x402 Metrics: Observability Wrapper
207
265
 
208
- Wrap your `x402Serve` handler with `x402Metrics` to get Prometheus-format counters, histograms, and revenue tracking — no changes to your payment logic.
266
+ Wrap your `x402Serve` handler with `x402Metrics` to get Prometheus-format counters, histograms, and revenue tracking - no changes to your payment logic.
209
267
 
210
268
  ```typescript
211
269
  import express from 'express';
@@ -273,7 +331,7 @@ x402_settlement_latency_seconds_sum{route="GET /signals"} 3.42
273
331
  x402_settlement_latency_seconds_count{route="GET /signals"} 8
274
332
  ```
275
333
 
276
- No payer addresses or PII are included in metrics output — aggregates only.
334
+ No payer addresses or PII are included in metrics output - aggregates only.
277
335
 
278
336
  ## Payouts
279
337
 
@@ -282,7 +340,7 @@ Batch disbursement, non-custodial: the node builds an **unsigned** transaction,
282
340
  ```typescript
283
341
  const run = await agent.createPayoutRun({
284
342
  recipients: [{ wallet: 'GABC...', amount: '250.00' }],
285
- acknowledgeTerms: true, // required on every network — 403 without it
343
+ acknowledgeTerms: true, // required on every network - 403 without it
286
344
  });
287
345
 
288
346
  const signedXdr = await signWithYourWallet(run.xdr);
@@ -290,23 +348,23 @@ const settled = await agent.submitPayout(run.runId, signedXdr);
290
348
  console.log(settled.txHash, settled.cid); // on-chain hash + IPFS receipt
291
349
  ```
292
350
 
293
- Licensed for **independent service payments only** — contractors, freelancers, B2B. Not for subordinate-employee salary. Read `getPayoutTerms()` before integrating; classifying recipients and meeting tax and labor obligations is the client's responsibility.
351
+ Licensed for **independent service payments only** - contractors, freelancers, B2B. Not for subordinate-employee salary. Read `getPayoutTerms()` before integrating; classifying recipients and meeting tax and labor obligations is the client's responsibility.
294
352
 
295
353
  Mainnet is invite-only during early access and additionally requires `clientInfo`.
296
354
 
297
355
  ## Treasury Rebalance
298
356
 
299
- Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap — the contract's `rebalance()` exposes exactly two instructions, `Unwind` and `Invest`, and neither accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.
357
+ Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap - the contract's `rebalance()` exposes exactly two instructions, `Unwind` and `Invest`, and neither accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.
300
358
 
301
- ### Propose — you review and sign, available to everyone today
359
+ ### Propose: you review and sign, available to everyone today
302
360
 
303
- The agent decides what it would do, using the same decision logic as the autonomous signer below, but it never signs. Public, no allowlist, no invite required — works for any vault where you're already the on-chain rebalance manager.
361
+ The agent decides what it would do, using the same decision logic as the autonomous signer below, but it never signs. Public, no allowlist, no invite required - works for any vault where you're already the on-chain rebalance manager.
304
362
 
305
363
  ```typescript
306
364
  const proposal = await agent.proposeTreasuryRebalance({
307
365
  vault: 'CABC...',
308
366
  caller: 'GABC...', // must already be this vault's rebalanceManager on-chain
309
- enterAt: 2.5, // your own mandate — Nirium never supplies a default here
367
+ enterAt: 2.5, // your own mandate - Nirium never supplies a default here
310
368
  exitAt: 2.0,
311
369
  });
312
370
 
@@ -318,13 +376,13 @@ if (proposal.instructions.length) {
318
376
  }
319
377
  ```
320
378
 
321
- ### Autonomous — Nirium signs, invite-only during legal review
379
+ ### Autonomous: Nirium signs, invite-only during legal review
322
380
 
323
- `executeTreasuryRebalance()` has Nirium sign and submit with its own RebalanceManager key — full autonomy, no per-cycle approval. **This is invite-only while a specific legal question stays open**: whether executing on a client's behalf without taking custody still counts as regulated facilitation under Mexican law. It only runs against vaults explicitly allowlisted server-side; calling it against any other vault returns 403, and Nirium's mainnet infrastructure returns 501 for it entirely, since that box holds no signing key by design. Ask if you want autonomous execution today — otherwise, `proposeTreasuryRebalance()` above gives you the same decision-making with you as the one who signs.
381
+ `executeTreasuryRebalance()` has Nirium sign and submit with its own RebalanceManager key - full autonomy, no per-cycle approval. **This is invite-only while a specific legal question stays open**: whether executing on a client's behalf without taking custody still counts as regulated facilitation under Mexican law. It only runs against vaults explicitly allowlisted server-side; calling it against any other vault returns 403, and Nirium's mainnet infrastructure returns 501 for it entirely, since that box holds no signing key by design. Ask if you want autonomous execution today - otherwise, `proposeTreasuryRebalance()` above gives you the same decision-making with you as the one who signs.
324
382
 
325
383
  ## Audit Trail
326
384
 
327
- Anchor evidence to IPFS and get back a CID — an integrity seal, not notarization.
385
+ Anchor evidence to IPFS and get back a CID - an integrity seal, not notarization.
328
386
 
329
387
  ```typescript
330
388
  const anchor = await agent.anchorAuditRecord({
@@ -345,10 +403,8 @@ Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, s
345
403
 
346
404
  - [Documentation](https://nirium.xyz/docs)
347
405
  - [Developer Sandbox](https://nirium.xyz/sandbox)
348
- - [API Reference](https://nirium.xyz/docs/api)
349
- - [MCP Server Integration](https://nirium.xyz/docs/mcp)
350
- - [GitHub](https://github.com/nirium-protocol/nirium-sdk)
406
+ - [GitHub](https://github.com/nirium-protocol/nirium)
351
407
 
352
408
  ## License
353
409
 
354
- Apache 2.0 — Nirium Protocol
410
+ Apache 2.0 - Nirium Protocol
package/package.json CHANGED
@@ -1,16 +1,17 @@
1
1
  {
2
2
  "name": "nirium",
3
- "version": "0.16.0",
3
+ "version": "0.16.1",
4
4
  "description": "Autonomous treasury and agentic-payments infrastructure for Stellar (x402)",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "homepage": "https://nirium.xyz",
8
8
  "repository": {
9
9
  "type": "git",
10
- "url": "git+https://github.com/nirium-protocol/nirium-sdk.git"
10
+ "url": "git+https://github.com/nirium-protocol/nirium.git",
11
+ "directory": "packages/sdk"
11
12
  },
12
13
  "bugs": {
13
- "url": "https://github.com/nirium-protocol/nirium-sdk/issues",
14
+ "url": "https://github.com/nirium-protocol/nirium/issues",
14
15
  "email": "niriumprotocol@gmail.com"
15
16
  },
16
17
  "author": {