nirium 0.18.0 → 0.19.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.
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # nirium
2
2
 
3
- Autonomous treasury and agentic-payments infrastructure for **Nirium Protocol** on Stellar/Soroban.
3
+ Verifiable receipts, agentic payments and treasury execution for **Nirium Protocol** on Stellar/Soroban.
4
4
 
5
- Nirium agents rebalance USDC ↔ CETES (tokenized Mexican T-bills via Etherfuse) 24/7 without human intervention. Built for developers who want to integrate autonomous treasury management, agentic payments with x402 (in both directions: paying for other APIs with `initX402()` and charging for your own with `x402Serve()`), an experimental MPP Charge client, and real-time market data into their applications.
5
+ - **Audit Trail:** anchor a SHA-256 of any event to IPFS and get back a CID that anyone can re-check, optionally signed with your agent's own Stellar key so it also proves *who* declared it. See [Audit Trail](#audit-trail).
6
+ - **x402 payments, both directions:** pay for other APIs with `initX402()` and charge for your own with `x402Serve()`. An MPP Charge client is included, experimental.
7
+ - **Treasury:** a Nirium agent can rebalance USDC ↔ CETES (tokenized Mexican T-bills via Etherfuse) over a vault you own. It runs on its own on testnet; on mainnet, autonomous execution is invite-only and anyone can get a proposal they review and sign.
8
+
9
+ **Status:** x402 and Audit Trail run on Stellar mainnet; MPP Charge is testnet only; autonomous treasury execution on mainnet is invite-only. Every claim, with its network, date and transaction hash: [EVIDENCE.md](https://github.com/nirium-protocol/nirium/blob/main/EVIDENCE.md).
6
10
 
7
11
  ## Install
8
12
 
@@ -40,6 +44,47 @@ agent.subscribe((signal) => {
40
44
  });
41
45
  ```
42
46
 
47
+ ## Audit Trail
48
+
49
+ Anchor evidence to IPFS and get back a CID - an integrity seal, not notarization.
50
+
51
+ ```typescript
52
+ const anchor = await agent.anchorAuditRecord({
53
+ hash: 'sha-256:9f86d081...', // hash of your own file or event
54
+ tag: 'invoice-batch-jul',
55
+ });
56
+ console.log(anchor.cid);
57
+ ```
58
+
59
+ Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, so raw personal data would outlive any erasure request.
60
+
61
+ ### Signed receipts: prove who declared it
62
+
63
+ The CID proves the fact was not altered. Add `agent` and it also proves which key declared it: your agent signs `nirium-audit-v1:<sha256>` with its own Stellar key, locally. Only the signature and the public key are sent; an invalid signature is rejected with `400` and nothing is anchored.
64
+
65
+ ```typescript
66
+ import { Keypair } from '@stellar/stellar-sdk';
67
+
68
+ const kp = Keypair.fromSecret(process.env.AGENT_SECRET!);
69
+ const hash = '...'; // 64-hex sha-256 of your evidence
70
+ const signature = Buffer.from(kp.sign(Buffer.from(`nirium-audit-v1:${hash}`))).toString('base64');
71
+
72
+ const anchor = await agent.anchorAuditRecord({
73
+ hash,
74
+ tag: 'invoice-batch-jul',
75
+ agent: { key: kp.publicKey(), signature },
76
+ });
77
+ console.log(anchor.cid, anchor.attestedBy);
78
+ ```
79
+
80
+ ### Verify any receipt, without trusting Nirium
81
+
82
+ ```bash
83
+ npx nirium-cli verify <cid> --hash <64-hex-sha256>
84
+ ```
85
+
86
+ `nirium verify` fetches the document from IPFS, recomputes the hash and checks the ed25519 signature against the declared Stellar key. You can also paste a CID at [nirium.xyz/verify](https://nirium.xyz/verify), with no account. More in [docs/verify-audit-cid.md](https://github.com/nirium-protocol/nirium/blob/main/docs/verify-audit-cid.md).
87
+
43
88
  ## API Coverage
44
89
 
45
90
  | Category | Methods |
@@ -214,7 +259,7 @@ app.use('/premium', x402Serve({
214
259
  }));
215
260
  ```
216
261
 
217
- 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.
262
+ Runs on **your own server**, not Nirium's - `x402Serve()` is Express middleware you run in your own server code; Nirium doesn't operate, host, or route through anything here, is never in the payment path, and never sees your end users' requests.
218
263
 
219
264
  **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).
220
265
 
@@ -345,7 +390,7 @@ curl -s http://localhost:3000/metrics
345
390
  Output:
346
391
 
347
392
  ```
348
- # HELP x402_challenges_total Total402 payment challenges issued
393
+ # HELP x402_challenges_total Total 402 payment challenges issued
349
394
  # TYPE x402_challenges_total counter
350
395
  x402_challenges_total{route="GET /signals"} 12
351
396
  # HELP x402_verify_success_total Total successful payment verifications
@@ -363,7 +408,7 @@ x402_settle_fail_total{route="GET /signals"} 1
363
408
  # HELP x402_infra_errors_total Total facilitator/infrastructure errors (5xx)
364
409
  # TYPE x402_infra_errors_total counter
365
410
  x402_infra_errors_total{route="GET /signals"} 1
366
- # HELP x402_rejections_total Total403 rejections from protected-request hooks
411
+ # HELP x402_rejections_total Total 403 rejections from protected-request hooks
367
412
  # TYPE x402_rejections_total counter
368
413
  x402_rejections_total{route="GET /signals"} 1
369
414
  # HELP x402_revenue_total Revenue collected per route and asset
@@ -431,20 +476,6 @@ if (proposal.instructions.length) {
431
476
 
432
477
  `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.
433
478
 
434
- ## Audit Trail
435
-
436
- Anchor evidence to IPFS and get back a CID - an integrity seal, not notarization.
437
-
438
- ```typescript
439
- const anchor = await agent.anchorAuditRecord({
440
- hash: 'sha-256:9f86d081...', // hash of your own file or event
441
- tag: 'invoice-batch-jul',
442
- });
443
- console.log(anchor.cid);
444
- ```
445
-
446
- Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, so raw personal data would outlive any erasure request.
447
-
448
479
  ## Requirements
449
480
 
450
481
  - Node.js >= 22.12.0. `@stellar/stellar-sdk` 16 and `@x402/stellar` 2.28 declare `>=22.0.0`, but stellar-sdk 16 depends on `@noble/hashes` 2.x, which is ESM-only, and this package is published as CommonJS: `require('nirium')` only works without a flag from Node 22.12.0 (on 22.11 it throws `ERR_REQUIRE_ESM`)
@@ -453,7 +484,8 @@ Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, s
453
484
  ## Links
454
485
 
455
486
  - [Documentation](https://nirium.xyz/docs)
456
- - [Developer Sandbox](https://nirium.xyz/sandbox)
487
+ - [Build examples](https://nirium.xyz/build)
488
+ - [Verify a receipt](https://nirium.xyz/verify)
457
489
  - [GitHub](https://github.com/nirium-protocol/nirium)
458
490
 
459
491
  ## License
package/dist/index.d.ts CHANGED
@@ -292,6 +292,21 @@ export interface PayoutRun {
292
292
  pricing?: Record<string, unknown>;
293
293
  [key: string]: unknown;
294
294
  }
295
+ /**
296
+ * One entry of the public payout history (getPayoutRuns). It carries what is
297
+ * already public on-chain - amount, asset, recipient count and the tx - and
298
+ * never the run id or the IPFS receipt CID: the receipt is the paying
299
+ * company's evidence, returned only to whoever runs the payout (submitPayout).
300
+ */
301
+ export interface PublicPayoutRun {
302
+ network?: string;
303
+ asset?: string;
304
+ totalAmount?: string;
305
+ recipientCount?: number;
306
+ txHash?: string;
307
+ explorer?: string;
308
+ signed?: boolean;
309
+ }
295
310
  export interface AgentAttestationInput {
296
311
  /** ed25519 public key of the agent, as a Stellar address (G...). */
297
312
  key: string;
@@ -717,9 +732,13 @@ export declare class Agent {
717
732
  }>;
718
733
  /** Broadcast the signed trustline XDR from onboardPayoutRecipient. */
719
734
  submitPayoutOnboard(signedXdr: string): Promise<Record<string, unknown>>;
720
- /** Payout history for the current network, each with tx hash and IPFS receipt CID. */
735
+ /**
736
+ * Public payout history for the current network: amount, asset, recipient
737
+ * count and tx hash. It does not include run ids or IPFS receipt CIDs; your
738
+ * own run's CID comes back from submitPayout().
739
+ */
721
740
  getPayoutRuns(): Promise<{
722
- runs: PayoutRun[];
741
+ runs: PublicPayoutRun[];
723
742
  }>;
724
743
  /** Payouts Terms v1.0 — the text `acknowledgeTerms` accepts. */
725
744
  getPayoutTerms(): Promise<Record<string, unknown>>;
package/dist/index.js CHANGED
@@ -342,7 +342,11 @@ class Agent {
342
342
  async submitPayoutOnboard(signedXdr) {
343
343
  return this.request('POST', '/api/payroll/onboard/submit', { signedXdr });
344
344
  }
345
- /** Payout history for the current network, each with tx hash and IPFS receipt CID. */
345
+ /**
346
+ * Public payout history for the current network: amount, asset, recipient
347
+ * count and tx hash. It does not include run ids or IPFS receipt CIDs; your
348
+ * own run's CID comes back from submitPayout().
349
+ */
346
350
  async getPayoutRuns() {
347
351
  return this.request('GET', '/api/payroll/runs');
348
352
  }
package/dist/metrics.js CHANGED
@@ -106,13 +106,13 @@ function renderPrometheus(state) {
106
106
  lines.push(`${name}{route="${route}"} ${value}`);
107
107
  }
108
108
  };
109
- writeCounter('x402_challenges_total', 'Total402 payment challenges issued', state.challenges);
109
+ writeCounter('x402_challenges_total', 'Total 402 payment challenges issued', state.challenges);
110
110
  writeCounter('x402_verify_success_total', 'Total successful payment verifications', state.vSuccess);
111
111
  writeCounter('x402_verify_fail_total', 'Total failed payment verifications', state.vFail);
112
112
  writeCounter('x402_settle_success_total', 'Total successful settlements', state.sSuccess);
113
113
  writeCounter('x402_settle_fail_total', 'Total failed settlements', state.sFail);
114
114
  writeCounter('x402_infra_errors_total', 'Total facilitator/infrastructure errors (5xx)', state.infraErrors);
115
- writeCounter('x402_rejections_total', 'Total403 rejections from protected-request hooks', state.rejections);
115
+ writeCounter('x402_rejections_total', 'Total 403 rejections from protected-request hooks', state.rejections);
116
116
  // Revenue — only emitted when there is data
117
117
  if (Object.keys(state.revenue).length > 0) {
118
118
  lines.push('# HELP x402_revenue_total Revenue collected per route and asset');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium",
3
- "version": "0.18.0",
3
+ "version": "0.19.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",