nirium-pollar-adapter 0.6.0 → 0.6.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.
Files changed (2) hide show
  1. package/README.md +23 -9
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,11 +1,21 @@
1
1
  # nirium-pollar-adapter
2
2
 
3
+ [![CI](https://github.com/nirium-protocol/nirium-pollar-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/nirium-protocol/nirium-pollar-adapter/actions/workflows/ci.yml)
4
+ [![Security Gate](https://github.com/nirium-protocol/nirium-pollar-adapter/actions/workflows/security-gate.yml/badge.svg)](https://github.com/nirium-protocol/nirium-pollar-adapter/actions/workflows/security-gate.yml)
5
+ [![npm](https://img.shields.io/npm/v/nirium-pollar-adapter)](https://www.npmjs.com/package/nirium-pollar-adapter)
6
+
3
7
  Nirium adapter for the [Pollar](https://pollar.xyz) SDK. It lets the wallet a user onboarded through Pollar pay for APIs (x402) and anchor tamper-proof evidence to IPFS, without your app touching keys or learning the x402 protocol.
4
8
 
5
- Both surfaces are **software-only and non-custodial**, and both are **live on Stellar mainnet**.
9
+ Two things matter most here: **x402** pays per request, and `anchorOnTransactionSuccess()` (see [API](#api) below) anchors an Audit Trail receipt to IPFS for every Pollar transaction that reaches `success` - a verifiable, tamper-proof record of what happened, independent of this adapter's own output.
10
+
11
+ Both surfaces are **software-only and non-custodial**, and both are **live on Stellar mainnet**: the last x402 payment settled on [29 Sep 2026](https://stellar.expert/explorer/public/tx/b34630f6637d6773ad4f7378dac8690ae6d1809173ff9c9541d22165aeef5788) (a real USDC transfer on mainnet), and the last Audit Trail anchor is from 12 Nov 2026, checked live against the mainnet agent's `GET /api/reporting/summary?network=mainnet` at the time of writing (`anchors.lastAnchoredAt`).
6
12
 
7
13
  Wraps [`nirium`](https://github.com/nirium-protocol/nirium), the TypeScript/Python SDK this adapter signs for. See that repo for the full API this exposes through a Pollar wallet instead of a raw keypair.
8
14
 
15
+ **Referenced by Pollar.** Pollar's official [x402 payments guide](https://docs.pollar.xyz/docs/guides/x402-payments) uses this adapter and Nirium's endpoints as its "Try it against Nirium" example (checked 14 Nov 2026). That is a documentation reference, not Pollar using Nirium in its own product.
16
+
17
+ **Try it in a browser:** [nirium-pollar-x402-demo.vercel.app](https://nirium-pollar-x402-demo.vercel.app) (testnet): log in with Pollar, pay 0.05 test USDC, open the receipt at nirium.xyz/verify.
18
+
9
19
  ## Install
10
20
 
11
21
  ```bash
@@ -38,7 +48,7 @@ The user pays **$0.05 USDC** and signs nothing else. The x402 facilitator sponso
38
48
 
39
49
  ### Requires @pollar/core 0.11.4+
40
50
 
41
- `createPollarSigner` calls `PollarClient.signAuthEntry`, available from `@pollar/core` 0.11. The peer range is `>=0.11.4 <0.13.0`; CI runs the contract test against 0.11.4; 0.12.0 was also run by hand on 2026-10-31. On older versions it throws an explanatory error, and you can still pass any other SEP-43 signer.
51
+ `createPollarSigner` calls `PollarClient.signAuthEntry`, available from `@pollar/core` 0.11. The peer range is `>=0.11.4 <0.13.0`; CI runs the type check and the full test suite against both ends of it, 0.11.4 and 0.12.0. On older versions it throws an explanatory error, and you can still pass any other SEP-43 signer.
42
52
 
43
53
  The two sides speak different dialects and the adapter translates between them: x402 expects SEP-43 (`signAuthEntry(xdr, { networkPassphrase, address }) → { signedAuthEntry }`), Pollar expects `signAuthEntry(xdr, { validUntilLedger }) → { status, … }`. The adapter reads the network's latest ledger, sets the expiry, and normalises the outcome. You do not deal with any of it.
44
54
 
@@ -58,6 +68,8 @@ import { canSignX402 } from "nirium-pollar-adapter";
58
68
 
59
69
  ## Verify it end-to-end today
60
70
 
71
+ **Demo app:** the Nirium demo in `pollar-xyz/pollar-apps` had a real `XDR Read Error` on payment. The fix, plus USDC balance, receipt links and clear Pollar error messages, is in [pollar-xyz/pollar-apps#37](https://github.com/pollar-xyz/pollar-apps/pull/37) (open, awaiting Pollar's review; it includes the earlier #36). The live demo already runs that branch: a testnet payment through it settled on 15 Nov 2026 UTC ([`75c8b590…`](https://stellar.expert/explorer/testnet/tx/75c8b590d2ddef1b0d082df43f90cad9ac4d1014678e3d8b34df8dae284c8fb0)) and its receipt verifies at [nirium.xyz/verify](https://nirium.xyz/verify?cid=QmcwsCMfd53mSFAXocRqTXdiJkAkU6DnRf9Dup7pR8Y6EZ). That payment was our own test.
72
+
61
73
  The signer is pluggable, so you can prove the whole path works with a plain Stellar keypair. No Pollar required - this defaults to testnet, no real money moves:
62
74
 
63
75
  ```bash
@@ -170,7 +182,7 @@ the signer a **`HashIdPreimage`** (the thing about to be hashed) and expects
170
182
  the **raw signature** back; it assembles the final entry itself. Pollar's
171
183
  `POST /tx/sign-auth-entry` expects the full **`SorobanAuthorizationEntry`** and
172
184
  returns the **signed entry**, because its backend checks the invocation tree
173
- against your Auth Policy allowlist before signing, and a hash would tell it
185
+ against your app's signing rules before signing, and a hash would tell it
174
186
  nothing. Both designs are right; they are just not the same one.
175
187
 
176
188
  Without translation Pollar answers `SOROBAN_AUTH_ENTRY_INVALID - "entryXdr is
@@ -211,7 +223,7 @@ const stop = anchorOnTransactionSuccess(pollar, adapter, {
211
223
 
212
224
  The receipt carries only `chain`, `network`, `hash` and `observedAt` (no app id), because what goes into IPFS is not deleted. Pollar replays the current state when you subscribe, so the function deduplicates by hash inside the process. It does not deduplicate across restarts: the same hash can be anchored twice. A failed anchor goes to `onError` and never throws into Pollar's listener; the hash can be retried when Pollar sends it again. Options: `chain` (default `"stellar"`), `tag` (default `"pollar-tx"`), `onError`.
213
225
 
214
- Checked against `@pollar/core` 0.11.4 and 0.12.0 in the test suite.
226
+ Checked against `@pollar/core` 0.11.4 and 0.12.0 in CI.
215
227
 
216
228
  **Live check, 2026-11-01, testnet.** `examples/spike-19/anchor-on-success.mjs` logs in to a Pollar testnet app, sends 1 XLM through `pollar.sendPayment`, and anchors the receipt. Transaction [`95717202...b7b`](https://horizon-testnet.stellar.org/transactions/95717202be514ed0ae6d59d88c5950d79ff94b40dad709a430691ad6c4449b7b) (successful, ledger 5506358, 1 payment op) produced Audit Trail receipt [`QmboKKkuwck3zvRx2bqnzUdDFkrEtc1VUHo6rrzm9nyBtD`](https://gateway.pinata.cloud/ipfs/QmboKKkuwck3zvRx2bqnzUdDFkrEtc1VUHo6rrzm9nyBtD). The record holds only `chain`, `network`, `hash` and `observedAt`, and `content_sha256` equals the sha-256 of that record as sent. This is a Nirium self-test on testnet, not third-party use.
217
229
 
@@ -229,9 +241,11 @@ that point somewhere else:
229
241
  Client side, `connect-src` must list the resource server, the Soroban RPC and
230
242
  `sdk.api.pollar.xyz`.
231
243
 
232
- Pollar side: allowlist the USDC SAC with the `transfer` function under
233
- **Treasury → Auth Policy**. Until a contract is listed, every custodial signing
234
- request is rejected.
244
+ Pollar side (dashboard names as in Pollar's [x402 guide](https://docs.pollar.xyz/docs/guides/x402-payments)):
245
+ under **Wallets → Signing rules**, add the USDC SAC with the function `transfer`,
246
+ in lowercase (`Transfer` authorizes nothing). Until a contract is listed, every
247
+ custodial signing request is rejected. Also enable USDC under **Tokens**, so
248
+ wallets get the trustline.
235
249
 
236
250
  ## How this relates to Pollar's `AdapterFn` pattern
237
251
 
@@ -245,7 +259,7 @@ In practice:
245
259
  - Nirium operations that do return an unsigned transaction (treasury, payouts) are not exposed here as `AdapterFn`s. They are invite-only on mainnet and outside the scope of this package.
246
260
  - A registry-pattern version of the payment flow is not shipped. Whether one is possible depends on how an adapter could hand back a signed authorization entry instead of a transaction. That is an open design question, not a plan.
247
261
 
248
- Checked on 2026-10-12 against the published `@pollar/core` 0.11.4 and `@pollar/react` 0.11.4 packages, not their docs. CI runs a contract test against the real `@pollar/core` 0.11.4 (`test/pollar-contract.test.mjs` and a compile-time check in `test/pollar-contract.types.ts`), so a change in the shape this package relies on fails the build.
262
+ Checked on 2026-10-12 against the published `@pollar/core` 0.11.4 and `@pollar/react` 0.11.4 packages, not their docs. CI runs a contract test against the real `@pollar/core` 0.11.4 and 0.12.0 (`test/pollar-contract.test.mjs` and a compile-time check in `test/pollar-contract.types.ts`), so a change in the shape this package relies on fails the build.
249
263
 
250
264
  ## Scope
251
265
 
@@ -253,7 +267,7 @@ Checked on 2026-10-12 against the published `@pollar/core` 0.11.4 and `@pollar/r
253
267
  |---|---|
254
268
  | x402 Settlement | ✅ mainnet |
255
269
  | Audit Trail (IPFS) | ✅ mainnet |
256
- | Treasury vault (DeFindex, client-owned), Nirium signs and executes | ✅ mainnet, invite-only during legal review |
270
+ | Treasury vault (DeFindex, client-owned), Nirium signs and executes | ✅ mainnet, invite-only until a written legal opinion |
257
271
  | Treasury vault, propose only, you sign | ✅ mainnet, public, no invite required (`POST /api/treasury/rebalance/propose`, not yet wrapped by this adapter) |
258
272
  | Nirium's own NiriumVault | audit-gated, testnet only |
259
273
  | MPP session channels | audit-gated, testnet only |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium-pollar-adapter",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Nirium adapter for the Pollar SDK — x402 pay-per-request and IPFS audit anchoring using the wallet a user onboarded through Pollar. Signs SEP-43 auth entries; the facilitator sponsors network fees. Includes Deferred-mode wallet activation (POST /v1/wallets/activate).",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -20,9 +20,9 @@
20
20
  },
21
21
  "dependencies": {
22
22
  "@stellar/stellar-sdk": "^16.4.1",
23
- "@x402/core": "2.29.0",
24
- "@x402/fetch": "2.29.0",
25
- "@x402/stellar": "2.29.0"
23
+ "@x402/core": "2.31.0",
24
+ "@x402/fetch": "2.31.0",
25
+ "@x402/stellar": "2.31.0"
26
26
  },
27
27
  "peerDependencies": {
28
28
  "@pollar/core": ">=0.11.4 <0.13.0"
@@ -33,8 +33,8 @@
33
33
  }
34
34
  },
35
35
  "devDependencies": {
36
- "@pollar/core": "0.11.4",
37
- "@types/node": "^26.6.5",
36
+ "@pollar/core": "0.12.0",
37
+ "@types/node": "^26.6.6",
38
38
  "typescript": "^5.7.0"
39
39
  },
40
40
  "keywords": [