nirium 0.19.0 → 0.19.2
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 +54 -22
- package/dist/metrics.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# nirium
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Verifiable receipts, agentic payments and treasury execution for **Nirium Protocol** on Stellar/Soroban.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
@@ -405,7 +450,7 @@ Mainnet is invite-only during early access and additionally requires `clientInfo
|
|
|
405
450
|
|
|
406
451
|
## Treasury Rebalance
|
|
407
452
|
|
|
408
|
-
Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap
|
|
453
|
+
Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap. The contract's `rebalance()` accepts four instructions (`Unwind`, `Invest`, `SwapExactIn`, `SwapExactOut`); these methods only send `Unwind` and `Invest`. None of the four accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.
|
|
409
454
|
|
|
410
455
|
### Propose: you review and sign, available to everyone today
|
|
411
456
|
|
|
@@ -427,24 +472,10 @@ if (proposal.instructions.length) {
|
|
|
427
472
|
}
|
|
428
473
|
```
|
|
429
474
|
|
|
430
|
-
### Autonomous: Nirium signs, invite-only
|
|
475
|
+
### Autonomous: Nirium signs, invite-only until a written legal opinion
|
|
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
|
-
- [
|
|
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/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', '
|
|
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', '
|
|
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');
|