@wzrd_sol/eliza-plugin 0.8.1 → 0.10.0

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
@@ -19,8 +19,12 @@ Before any x402 spend:
19
19
  3. **Optional paid trust** - `WZRD_INTEL_TRUST` (~0.05 USDC) - full score + **signed V7 receipt**
20
20
  4. **Offline verify** - `WZRD_VERIFY_RECEIPT` via `twzrd-receipt-verifier`
21
21
 
22
- This plugin exposes **actions + SDK helpers**. It does **not** auto-intercept every wallet signature.
23
- Wire `preSpendGate` / actions into your spend path, or compose with standalone `twzrd-x402-gate` on a paying fetch.
22
+ This plugin exposes **actions + SDK helpers**. The free checks above do not enforce anything by
23
+ themselves: an action refuses only its own paid lookup, and nothing here intercepts a signature your
24
+ agent makes elsewhere. **`installTwzrdAutoGate` is what enforces.** It guards the raw fetch before your
25
+ x402 client's `payWrap` signs, so a payment made through the plugin's paying fetch is checked first
26
+ (see [Guard pattern](#guard-pattern-installtwzrdautogate)). A spend path that does not go through that
27
+ fetch needs its own gate, such as `preSpendGate` or standalone `twzrd-x402-gate`.
24
28
 
25
29
  ## 3-line quickstart
26
30
 
@@ -71,7 +75,7 @@ npm install @wzrd_sol/eliza-plugin
71
75
 
72
76
  Classification uses the verifier domain allowlist only. Envelope `version` / `kind` cannot promote a V6 body to V7.
73
77
 
74
- `verifyReceipt` and `getIntelClient().verify` are **synchronous**. They do not accept `fetchPubkey` / `apiBase` (0.6.1 SDK path) and return `receiptVersion` + `freshness` instead of SDK `leafVersion`. Default signing key is `CURRENT_RECEIPT_PUBKEY` (v2). Do not pass SDK `TRUSTED_RECEIPT_PUBKEY` (v1) or live V7 receipts fail closed.
78
+ `verifyReceipt` and `getIntelClient().verify` are **synchronous**. They do not accept `fetchPubkey` / `apiBase` (0.6.1 SDK path) and return `receiptVersion` + `freshness` instead of SDK `leafVersion`. Default signing key is `CURRENT_RECEIPT_PUBKEY` (v2). The re-exported SDK `TRUSTED_RECEIPT_PUBKEY` is the same v2 key from 0.10.0 on. The legacy v1 key (`LEGACY_RECEIPT_PUBKEYS[0]` in `@wzrd_sol/sdk`) fails live V7 receipts closed.
75
79
 
76
80
  ### Preflight (free, no wallet)
77
81
 
@@ -124,6 +128,17 @@ const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
124
128
  `payWrap` receives the **guarded** fetch. Opt out with `TWZRD_AUTO_GATE=0` or `{ disabled: true }`.
125
129
  Lookups carry `X-TWZRD-Integration: eliza-plugin/<version>` unless you pass your own `attribution`.
126
130
 
131
+ On `twzrd-x402-gate` 0.14.0 the guard refuses each of these before `payWrap` signs (the 0.13 defaults, unchanged in 0.14.0):
132
+
133
+ | Refused by default | Reason | Opt out (restores the 0.12.5 outcome) |
134
+ |---|---|---|
135
+ | A merchant card that has not fully answered the wash question, including a wallet intel has never seen | `twzrd_wash_unknown` | `{ refuseWashUnknown: false }` or `TWZRD_REFUSE_WASH_UNKNOWN=0` |
136
+ | An evaluated `warn` with no `recommended_cap_usdc`, or at an unknown price | `twzrd_warn_no_cap`, `twzrd_warn_unknown_price` | `{ refuseUncappedWarn: false }` or `TWZRD_REFUSE_UNCAPPED_WARN=0` |
137
+ | A seller intel has never evaluated (`score: null` or `null_reason` set), even within its cap | `twzrd_unevaluated_subject_<null_reason>` | `{ refuseUnevaluated: false }` or `TWZRD_REFUSE_UNEVALUATED=0` |
138
+
139
+ An unreachable card is still an outage, decided by `failOpen`. The env opt-outs also accept
140
+ `false`, `no` and `off`; any other value leaves the refusal on.
141
+
127
142
  ### Paid trust receipt
128
143
 
129
144
  ```typescript
@@ -139,14 +154,45 @@ const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
139
154
 
140
155
  Without a paying fetch, `WZRD_INTEL_TRUST` returns the HTTP 402 requirements.
141
156
 
157
+ ## 0.10.0 changes
158
+
159
+ - Depends on `@wzrd_sol/sdk` `^0.5.1` (was `^0.4.8`) and on `twzrd-x402-gate` exactly `0.14.0` (was `0.13.1`),
160
+ the first gate release that exports `createDemandDeskWallet`. The guard's refusal defaults are those of
161
+ 0.13.1. Fetches this plugin owns stamp `X-Twzrd-Caller: eliza-plugin/<version>@0.14.0`.
162
+ - The re-exported `TRUSTED_RECEIPT_PUBKEY` is now the v2 receipt key, equal to `CURRENT_RECEIPT_PUBKEY`.
163
+ It was the v1 key. If you verify old v1-signed receipts, pass `LEGACY_RECEIPT_PUBKEYS[0]` from
164
+ `@wzrd_sol/sdk` explicitly.
165
+ - A preflight answer without a known decision is now an error (`preflight_invalid_payload`), not a
166
+ result. `WZRD_INTEL_TRUST` refuses with no spend; SDK 0.4 read such an answer as `warn` and let the
167
+ paid lookup go ahead. `WZRD_INTEL_PREFLIGHT` returns `refuse_pay: true` (`preflight_unavailable`)
168
+ where it used to report the answer as a card. `getIntelClient().preflight` rejects instead of
169
+ resolving.
170
+ - No new paid call. SDK 0.5's `preSpendGate` can escalate to the paid quick lookup, but only when
171
+ `escalateAboveUsdc` is set, and this plugin does not set it.
172
+ - Adds `createDemandDeskWalletProvider` and `createWzrdPlugin({ walletProvider })`: a guarded
173
+ Demand Desk wallet provider for host spend actions, built on `twzrd-x402-gate`'s
174
+ `createDemandDeskWallet`.
175
+
176
+ ## 0.9.0 changes
177
+
178
+ - Depends on `twzrd-x402-gate` exactly `0.13.1` (was `0.12.5`). Fetches this plugin owns stamp
179
+ `X-Twzrd-Caller: eliza-plugin/<version>@0.13.1`.
180
+ - `installTwzrdAutoGate` now refuses more before your pay client signs: an unanswered wash question,
181
+ an uncapped or unpriced `warn`, and a seller intel has never evaluated. The table under
182
+ [Guard pattern](#guard-pattern-installtwzrdautogate) lists each reason and its opt-out.
183
+ - The actions' own checks are unchanged. `WZRD_INTEL_TRUST` still runs the SDK's `preSpendGate`, which
184
+ refuses `wash_flagged: true` and a missing merchant card, and reports incomplete wash coverage
185
+ without refusing it. When the paying fetch comes from `installTwzrdAutoGate`, the paid call itself
186
+ also goes through the guard above.
187
+
142
188
  ## 0.8.0 changes (breaking)
143
189
 
144
190
  - Removed the retired earn actions, `legacyEarnActions`, `wzrdPluginWithLegacyEarn`, `WzrdClient`,
145
191
  `getWzrdClient` and `clearClientCache`. The plugin no longer reads `SOLANA_PRIVATE_KEY` or `WZRD_API_URL`.
146
192
  - `WZRD_INTEL_TRUST` spends only with `WZRD_INTEL_ALLOW_PAID=true` or `confirm_spend: true`.
147
193
  - `WZRD_MERCHANT_CARD` is fail-closed when the card is unavailable (`refuse_pay: true`).
148
- - A paid trust lookup also refuses, with no spend, when that card lookup does not answer. A card that answers with incomplete wash coverage is reported, not refused, on gate 0.12.5 (`refuseWashUnknown` stays opt-in until 0.13.0).
149
- - Depends on `twzrd-x402-gate` exactly `0.12.5`. Fetches this plugin owns stamp `X-Twzrd-Caller: eliza-plugin/<version>@0.12.5`.
194
+ - A paid trust lookup also refuses, with no spend, when that card lookup does not answer. A card that answers with incomplete wash coverage is reported, not refused (0.9.0 keeps this for the action's own check).
195
+ - Depended on `twzrd-x402-gate` exactly `0.12.5`. 0.9.0 moves the pin to `0.13.1`.
150
196
 
151
197
  ## Programmatic SDK usage
152
198
 
@@ -85,7 +85,8 @@ export const intelTrustAction = {
85
85
  };
86
86
  }
87
87
  // The SDK returns allow=true with merchantCard=null when the card lookup
88
- // cannot finish. 0.12.x does not refuse unknown coverage; a missing card does.
88
+ // cannot finish. The SDK's preSpendGate refuses only wash_flagged=true, not
89
+ // incomplete coverage; a missing card does refuse here.
89
90
  if (gate.merchantCard == null) {
90
91
  await callback?.({
91
92
  text: `Merchant card unavailable for ${pubkey}, so the wash check could not finish. ` +
@@ -47,7 +47,7 @@ function formatMerchantCard(card, coverage) {
47
47
  lines.push('Policy: do not pay this pay_to (trustless default). Cap only if operator set washMaxUsdc.');
48
48
  }
49
49
  else if (card.wash_flagged !== false || !coverage.coverageFull) {
50
- lines.push('Wash status unknown: not a clean bill. Strict hosts (twzrd-x402-gate refuseWashUnknown) refuse this pay_to.');
50
+ lines.push('Wash status unknown: not a clean bill. twzrd-x402-gate 0.13 refuses this pay_to by default (refuseWashUnknown).');
51
51
  }
52
52
  return lines.join('\n');
53
53
  }
@@ -0,0 +1,18 @@
1
+ import { type DemandDeskWalletAdapter } from 'twzrd-x402-gate';
2
+ import type { Provider } from '@elizaos/core';
3
+ /** Host wallet provider for spend actions. Keep the raw adapter private; actions
4
+ * receive only this facade. The intel-only plugin has no wallet to replace and
5
+ * cannot intercept unrelated third-party plugins that retain their own keys. */
6
+ export declare function createDemandDeskWalletProvider<T>(adapter: DemandDeskWalletAdapter<T>): Readonly<{
7
+ name: "TWZRD_DEMAND_DESK_WALLET";
8
+ description: "Guarded wallet capability for host spend actions under Demand Desk authorization.";
9
+ get: Provider["get"];
10
+ getWallet: () => Readonly<{
11
+ signTransaction: (tx: T, context: import("twzrd-x402-gate").DemandDeskWalletContext) => Promise<T>;
12
+ signAllTransactions(items: readonly {
13
+ transaction: T;
14
+ context: import("twzrd-x402-gate").DemandDeskWalletContext;
15
+ }[]): Promise<T[]>;
16
+ signAndSendTransaction(tx: T, context: import("twzrd-x402-gate").DemandDeskWalletContext): Promise<string>;
17
+ }>;
18
+ }>;
@@ -0,0 +1,17 @@
1
+ import { createDemandDeskWallet } from 'twzrd-x402-gate';
2
+ /** Host wallet provider for spend actions. Keep the raw adapter private; actions
3
+ * receive only this facade. The intel-only plugin has no wallet to replace and
4
+ * cannot intercept unrelated third-party plugins that retain their own keys. */
5
+ export function createDemandDeskWalletProvider(adapter) {
6
+ const wallet = createDemandDeskWallet(adapter);
7
+ return Object.freeze({
8
+ name: 'TWZRD_DEMAND_DESK_WALLET',
9
+ description: 'Guarded wallet capability for host spend actions under Demand Desk authorization.',
10
+ get: (async () => ({
11
+ text: 'Spend actions must use the configured Demand Desk wallet capability.',
12
+ data: { wallet },
13
+ values: { demandDeskWalletRequired: true },
14
+ })),
15
+ getWallet: () => wallet,
16
+ });
17
+ }
package/dist/index.d.ts CHANGED
@@ -9,13 +9,16 @@
9
9
  *
10
10
  * 0.8.0 removed the retired earn actions (infer/report/earn/claim/rewards).
11
11
  */
12
- import type { Action, Plugin } from '@elizaos/core';
12
+ import type { Action, Plugin, Provider } from '@elizaos/core';
13
13
  import { intelPreflightAction } from './actions/intel-preflight.js';
14
14
  import { merchantCardAction } from './actions/merchant-card.js';
15
15
  import { intelTrustAction } from './actions/intel-trust.js';
16
16
  import { verifyReceiptAction } from './actions/verify-receipt.js';
17
+ export { createDemandDeskWalletProvider } from './demand-desk-wallet.js';
17
18
  export declare const intelActions: Action[];
18
- export declare function createWzrdPlugin(): Plugin;
19
+ export declare function createWzrdPlugin(options?: {
20
+ walletProvider?: Provider;
21
+ }): Plugin;
19
22
  /** Default plugin: intel actions only (0.6+). */
20
23
  export declare const wzrdPlugin: Plugin;
21
24
  export default wzrdPlugin;
@@ -24,7 +27,7 @@ export { getIntelApiBase, getIntelClient } from './client-factory.js';
24
27
  export { setPayingFetch, clearPayingFetch, resolvePayingFetch, installTwzrdAutoGate, autoGateOptions, withTracking, callerTag, GATE_PIN, } from './paying-fetch.js';
25
28
  export { refusePacket, paidLookupConfirmed } from './actions/intel-trust.js';
26
29
  export type { RefusePacket } from './actions/intel-trust.js';
27
- /** SDK intel helpers. TRUSTED_RECEIPT_PUBKEY is the v1 key — use CURRENT_RECEIPT_PUBKEY for V7 verify. */
30
+ /** SDK intel helpers. From SDK 0.5, TRUSTED_RECEIPT_PUBKEY is the v2 key, equal to CURRENT_RECEIPT_PUBKEY. */
28
31
  export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, fetchMerchantCard, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';
29
32
  export { verifyReceipt, classifyReceipt, describeReceiptSurface, freshnessStatusFor, freshnessFromVerify, formatVerifyResult, CURRENT_RECEIPT_PUBKEY, CURRENT_RECEIPT_KEY_ID, REPUTATION_V5_DOMAIN, REPUTATION_V6_DOMAIN, REPUTATION_V7_DOMAIN, } from './receipt-verify.js';
30
33
  export type { VerifyReceiptResult, VerifyReceiptOptions, TwzrdReceiptLike, ReceiptVersion, FreshnessStatus, } from './receipt-verify.js';
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@ import { intelPreflightAction } from './actions/intel-preflight.js';
2
2
  import { merchantCardAction } from './actions/merchant-card.js';
3
3
  import { intelTrustAction } from './actions/intel-trust.js';
4
4
  import { verifyReceiptAction } from './actions/verify-receipt.js';
5
+ export { createDemandDeskWalletProvider } from './demand-desk-wallet.js';
5
6
  export const intelActions = [
6
7
  intelPreflightAction,
7
8
  merchantCardAction,
@@ -13,11 +14,12 @@ const INTEL_DESCRIPTION = 'TWZRD Agent Intel — free ReadinessCard preflight +
13
14
  'offline verify via twzrd-receipt-verifier. ' +
14
15
  'Legacy V6 verification is labeled freshness=derived_from_timestamp. ' +
15
16
  'Buyer sequence is call-site / action-driven (not an auto-interceptor of all payments).';
16
- export function createWzrdPlugin() {
17
+ export function createWzrdPlugin(options = {}) {
17
18
  return {
18
19
  name: 'wzrd',
19
20
  description: INTEL_DESCRIPTION,
20
21
  actions: [...intelActions],
22
+ ...(options.walletProvider ? { providers: [options.walletProvider] } : {}),
21
23
  };
22
24
  }
23
25
  /** Default plugin: intel actions only (0.6+). */
@@ -27,6 +29,6 @@ export { intelPreflightAction, merchantCardAction, intelTrustAction, verifyRecei
27
29
  export { getIntelApiBase, getIntelClient } from './client-factory.js';
28
30
  export { setPayingFetch, clearPayingFetch, resolvePayingFetch, installTwzrdAutoGate, autoGateOptions, withTracking, callerTag, GATE_PIN, } from './paying-fetch.js';
29
31
  export { refusePacket, paidLookupConfirmed } from './actions/intel-trust.js';
30
- /** SDK intel helpers. TRUSTED_RECEIPT_PUBKEY is the v1 key — use CURRENT_RECEIPT_PUBKEY for V7 verify. */
32
+ /** SDK intel helpers. From SDK 0.5, TRUSTED_RECEIPT_PUBKEY is the v2 key, equal to CURRENT_RECEIPT_PUBKEY. */
31
33
  export { IntelPaymentRequiredError, intelPreflight, fetchIntelTrust, fetchMerchantCard, preSpendGate, intelTrustUrl, TRUSTED_RECEIPT_PUBKEY, INTEL_TRUST_PRICE_USDC, } from '@wzrd_sol/sdk';
32
34
  export { verifyReceipt, classifyReceipt, describeReceiptSurface, freshnessStatusFor, freshnessFromVerify, formatVerifyResult, CURRENT_RECEIPT_PUBKEY, CURRENT_RECEIPT_KEY_ID, REPUTATION_V5_DOMAIN, REPUTATION_V6_DOMAIN, REPUTATION_V7_DOMAIN, } from './receipt-verify.js';
@@ -3,9 +3,9 @@ import { type InstallAutoGateOptions, type PayWrap } from 'twzrd-x402-gate';
3
3
  /** This package's version, stamped into X-TWZRD-Integration on gate lookups. */
4
4
  export declare const PLUGIN_VERSION: string;
5
5
  /** Exact twzrd-x402-gate pin. A caret would float onto a later line. */
6
- export declare const GATE_PIN = "0.12.5";
6
+ export declare const GATE_PIN = "0.14.0";
7
7
  export declare function integrationTag(): string;
8
- /** Seat stamp: X-Twzrd-Caller eliza-plugin/<version>@0.12.5. */
8
+ /** Seat stamp: X-Twzrd-Caller eliza-plugin/<version>@<GATE_PIN>. */
9
9
  export declare function callerTag(): string;
10
10
  /**
11
11
  * Stamp the four seat headers on an intel fetch. The SDK's own client header
@@ -6,11 +6,11 @@ const require = createRequire(import.meta.url);
6
6
  /** This package's version, stamped into X-TWZRD-Integration on gate lookups. */
7
7
  export const PLUGIN_VERSION = require('../package.json').version;
8
8
  /** Exact twzrd-x402-gate pin. A caret would float onto a later line. */
9
- export const GATE_PIN = '0.12.5';
9
+ export const GATE_PIN = '0.14.0';
10
10
  export function integrationTag() {
11
11
  return `eliza-plugin/${PLUGIN_VERSION}`;
12
12
  }
13
- /** Seat stamp: X-Twzrd-Caller eliza-plugin/<version>@0.12.5. */
13
+ /** Seat stamp: X-Twzrd-Caller eliza-plugin/<version>@<GATE_PIN>. */
14
14
  export function callerTag() {
15
15
  return `${integrationTag()}@${GATE_PIN}`;
16
16
  }
@@ -1,12 +1,13 @@
1
1
  /**
2
2
  * V7-capable receipt verification for the Eliza plugin.
3
3
  *
4
- * `@wzrd_sol/sdk` (through 0.4.8) only knows V5/V6 leaf bindings and defaults
5
- * to the legacy v1 signing key. Current paid trust issues V7 receipts that bind
6
- * freshness into the leaf and are signed with twzrd-receipt-ed25519-v2.
4
+ * Current paid trust issues V7 receipts that bind freshness into the leaf and
5
+ * are signed with twzrd-receipt-ed25519-v2. `@wzrd_sol/sdk` 0.5 also verifies
6
+ * V7, but its `verifyReceipt` is async and reports only `leafVersion`.
7
7
  *
8
- * This module routes through `twzrd-receipt-verifier@^1.4.0` and labels V6
9
- * results with the downgraded freshness status from docs/receipt-v6-spec.md.
8
+ * This module stays synchronous, routes through `twzrd-receipt-verifier@^1.4.0`,
9
+ * labels the version from the domain allowlist, and labels V6 results with the
10
+ * downgraded freshness status from docs/receipt-v6-spec.md.
10
11
  */
11
12
  import { createRequire } from 'node:module';
12
13
  export const REPUTATION_V5_DOMAIN = 'TWZRD:AO_REPUTATION_RECEIPT_V5';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wzrd_sol/eliza-plugin",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "description": "TWZRD Agent Intel for ElizaOS. Free preflight ReadinessCard + merchant_card (wash_flagged refuse default), paid GET /v1/intel/trust (~0.05 USDC) V7 receipt, offline verify via twzrd-receipt-verifier. Paid lookups need WZRD_INTEL_ALLOW_PAID or confirm_spend; merchant_card outages fail closed.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -18,9 +18,9 @@
18
18
  "typecheck": "echo 'eliza-plugin: typecheck ok'"
19
19
  },
20
20
  "dependencies": {
21
- "@wzrd_sol/sdk": "^0.4.8",
21
+ "@wzrd_sol/sdk": "^0.5.1",
22
22
  "twzrd-receipt-verifier": "^1.4.0",
23
- "twzrd-x402-gate": "0.12.5"
23
+ "twzrd-x402-gate": "0.14.0"
24
24
  },
25
25
  "peerDependencies": {
26
26
  "@elizaos/core": "^1.0.0"