nirium-pollar-adapter 0.6.1 → 0.6.3

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 +21 -11
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,5 +1,9 @@
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
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.
@@ -8,6 +12,10 @@ Both surfaces are **software-only and non-custodial**, and both are **live on St
8
12
 
9
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.
10
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
+
11
19
  ## Install
12
20
 
13
21
  ```bash
@@ -40,7 +48,7 @@ The user pays **$0.05 USDC** and signs nothing else. The x402 facilitator sponso
40
48
 
41
49
  ### Requires @pollar/core 0.11.4+
42
50
 
43
- `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.
44
52
 
45
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.
46
54
 
@@ -60,7 +68,7 @@ import { canSignX402 } from "nirium-pollar-adapter";
60
68
 
61
69
  ## Verify it end-to-end today
62
70
 
63
- **Known issue:** [pollar-xyz/pollar-apps#36](https://github.com/pollar-xyz/pollar-apps/pull/36) fixes a real `XDR Read Error` that breaks payment in Pollar's own official Nirium demo today; still open as of this writing.
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.
64
72
 
65
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:
66
74
 
@@ -174,7 +182,7 @@ the signer a **`HashIdPreimage`** (the thing about to be hashed) and expects
174
182
  the **raw signature** back; it assembles the final entry itself. Pollar's
175
183
  `POST /tx/sign-auth-entry` expects the full **`SorobanAuthorizationEntry`** and
176
184
  returns the **signed entry**, because its backend checks the invocation tree
177
- 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
178
186
  nothing. Both designs are right; they are just not the same one.
179
187
 
180
188
  Without translation Pollar answers `SOROBAN_AUTH_ENTRY_INVALID - "entryXdr is
@@ -215,7 +223,7 @@ const stop = anchorOnTransactionSuccess(pollar, adapter, {
215
223
 
216
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`.
217
225
 
218
- 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.
219
227
 
220
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.
221
229
 
@@ -233,9 +241,11 @@ that point somewhere else:
233
241
  Client side, `connect-src` must list the resource server, the Soroban RPC and
234
242
  `sdk.api.pollar.xyz`.
235
243
 
236
- Pollar side: allowlist the USDC SAC with the `transfer` function under
237
- **Treasury → Auth Policy**. Until a contract is listed, every custodial signing
238
- 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.
239
249
 
240
250
  ## How this relates to Pollar's `AdapterFn` pattern
241
251
 
@@ -249,7 +259,7 @@ In practice:
249
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.
250
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.
251
261
 
252
- 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.
253
263
 
254
264
  ## Scope
255
265
 
@@ -257,12 +267,12 @@ Checked on 2026-10-12 against the published `@pollar/core` 0.11.4 and `@pollar/r
257
267
  |---|---|
258
268
  | x402 Settlement | ✅ mainnet |
259
269
  | Audit Trail (IPFS) | ✅ mainnet |
260
- | Treasury vault (DeFindex, client-owned), Nirium signs and executes | ✅ mainnet, invite-only during legal review |
261
- | Treasury vault, propose only, you sign | ✅ mainnet, public, no invite required (`POST /api/treasury/rebalance/propose`, not yet wrapped by this adapter) |
270
+ | Treasury vault (DeFindex, client-owned), Nirium signs and executes | ✅ mainnet, invite-only until a written legal opinion |
271
+ | Treasury vault, propose only, you sign | ✅ testnet, open; mainnet, invite-only (`POST /api/treasury/rebalance/propose`, not yet wrapped by this adapter) |
262
272
  | Nirium's own NiriumVault | audit-gated, testnet only |
263
273
  | MPP session channels | audit-gated, testnet only |
264
274
 
265
- Nirium never holds customer funds. The user's signature is the authorization; regulated partners execute any financial settlement.
275
+ Nirium never holds customer funds. The user's signature is the authorization; independent partners execute any financial settlement.
266
276
 
267
277
  ## License
268
278
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nirium-pollar-adapter",
3
- "version": "0.6.1",
3
+ "version": "0.6.3",
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"
@@ -48,7 +48,7 @@
48
48
  "homepage": "https://nirium.xyz",
49
49
  "repository": {
50
50
  "type": "git",
51
- "url": "https://github.com/nirium-protocol/nirium-pollar-adapter.git"
51
+ "url": "git+https://github.com/nirium-protocol/nirium-pollar-adapter.git"
52
52
  },
53
53
  "bugs": {
54
54
  "url": "https://github.com/nirium-protocol/nirium-pollar-adapter/issues"