@gvnrdao/dh-sdk 0.0.337 → 0.0.339

package/dist/utils/sign-guard/tx-validator.d.ts

@@ -0,0 +1,148 @@
+import { type FeeCeiling } from "./fee-ceiling";
+/**
+ * Structural contract registry. `DeploymentContracts` from the SDK's deployment
+ * table satisfies it; test doubles and mock upstreams can fill it from their
+ * own sink constants without touching the registry.
+ */
+export interface ContractRegistry {
+    PositionManager?: string;
+    UCDToken?: string;
+    [name: string]: string | undefined;
+}
+export type ExpectedAction = {
+    kind: "mint";
+    positionId: string;
+    amountWei: string;
+    /**
+     * Audit H-2: required. An earlier shape made this optional, so a
+     * malicious or buggy server that omitted `mintFee` from its response
+     * silently bypassed the client pin and let the on-chain validator
+     * signature be the sole defense. Callers refuse to validate if the
+     * server did not echo the fee.
+     */
+    mintFeeWei: string;
+} | {
+    kind: "repay";
+    positionId: string;
+    amountWei: string;
+} | {
+    kind: "extend";
+    positionId: string;
+    selectedTerm: number;
+    /**
+     * Audit H-3: optional upper bound on the server-supplied
+     * `proRataRenewalFee` (args[5] of `extendPosition`). The validator
+     * decodes the value from the tx and refuses to sign if it exceeds this
+     * bound. Computed off-chain as `ucdDebt × extensionFeeRateBps / 10000`
+     * — the baseline-without-credit fee, which a compromised validator key
+     * could otherwise inflate to drain UCD. See `computeExtendFeeUpperBound`.
+     */
+    upperBoundProRataFeeWei?: string;
+} | {
+    kind: "withdraw-btc";
+    positionId: string;
+    btcAddress: string;
+    /**
+     * Audit M-9: upper bound on the on-chain `totalDeduction` (withdrawBTC
+     * params index 6 — the collateral debited from the vault). The validator
+     * refuses to sign if the value exceeds it, so a compromised
+     * server/validator cannot inflate the deduction beyond what the user
+     * approved. The CLI pins it to the requested `amountSats`, which is an
+     * exact bound: the LIT action defines `totalDeduction =
+     * withdrawalAmountInSats` and takes the network fee *out of* that total.
+     */
+    upperBoundTotalDeduction?: string;
+} | {
+    /**
+     * On-chain position creation (`PositionManager.createPosition`), reached
+     * via `sdk.createLoan`. Pins the target and the USER-INTENDED term;
+     * pkpId / vaults / validator payloads are server-derived and are
+     * displayed, never pinned.
+     */
+    kind: "create-position";
+    selectedTerm: number;
+}
+/** Server-built UCD allowance ahead of `makePayment`: min/cap band, spender SET. */
+ | {
+    kind: "ucd-approve";
+    spenderCandidates: string[];
+    minAmountWei: string;
+} | {
+    kind: "set-position-delegate";
+    positionId: string;
+    delegate: string;
+    registryAddress: string;
+}
+/** BitcoinWithdrawalAddressRegistry.addAddress — pins the registry target and the EXACT destination string. */
+ | {
+    kind: "bwar-add-address";
+    btcAddress: string;
+    registryAddress: string;
+}
+/**
+ * PSM pair. `ucd-approve` pins target=UCDToken with a min/cap band and a
+ * spender SET — it cannot express the PSM's asymmetric, EXACT-amount
+ * approvals, and is deliberately NOT widened. Each PSM expectation pins BOTH
+ * the token contract (tx target) and the ONE exact spender, and the amount
+ * EXACTLY (never a band — exact-amount approvals are the standing rule;
+ * the SDK's MaxUint256 helpers are banned on these paths). Addresses come
+ * from the caller's own registry so decode-equivalence stays registry-neutral.
+ */
+ | {
+    kind: "stablecoin-approve";
+    tokenAddress: string;
+    spender: string;
+    amountUnits: string;
+} | {
+    kind: "ucd-approve-controller";
+    ucdTokenAddress: string;
+    spender: string;
+    amountWei: string;
+} | {
+    kind: "psm-swap";
+    psmAddress: string;
+    stablecoin: string;
+    amountIn: string;
+    minOut: string;
+} | {
+    kind: "psm-redeem";
+    psmAddress: string;
+    stablecoin: string;
+    amountUcdWei: string;
+    minOut: string;
+};
+export interface ValidationContext {
+    chainId: number;
+    network: string;
+    contracts: ContractRegistry;
+    /** Omit for the SDK defaults; consumers with a user-raisable cap pass their own. */
+    feeCeiling?: FeeCeiling;
+}
+/**
+ * SDK-registry-backed validation context. Keys: `sepolia` | `localhost` |
+ * `mainnet`; `hardhat` / `local` are accepted as aliases for chainId 31337.
+ */
+export declare function buildValidationContext(network: string, chainId: number, feeCeiling?: FeeCeiling): ValidationContext;
+/**
+ * Validates a server-returned unsigned transaction against the action the user
+ * authorized. Throws `TxValidationError` on any mismatch.
+ *
+ * Defense in depth — the signed authMessage already binds chainId + positionId
+ * + amount, but only the server interprets that. This is the last line where
+ * the client can refuse to sign something the user did not approve.
+ */
+export declare function validateUnsignedTx(unsignedTx: Record<string, unknown>, expected: ExpectedAction, vctx: ValidationContext): void;
+/**
+ * Read the fee fields relevant to cost, for display. Never throws — a banner
+ * must not be the thing that fails a sign; `validateUnsignedTx` owns rejection.
+ */
+export declare function readTxFeeFields(unsignedTx: Record<string, unknown>): {
+    gasLimit: bigint | null;
+    maxFeePerGas: bigint | null;
+};
+/** Target, decoded function name (or `"<unparseable>"`) and chainId, for banners. */
+export declare function describeUnsignedTx(unsignedTx: Record<string, unknown>): {
+    to: string;
+    fn: string;
+    chainId: number | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.337",
+  "version": "0.0.339",
   "description": "TypeScript SDK for Diamond Hands Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,6 +34,11 @@
       "types": "./dist/safe-delegation.d.ts",
       "import": "./dist/safe-delegation.mjs",
       "require": "./dist/safe-delegation.js"
+    },
+    "./sign-guard": {
+      "types": "./dist/sign-guard.d.ts",
+      "import": "./dist/sign-guard.mjs",
+      "require": "./dist/sign-guard.js"
     }
   },
   "files": [
@@ -66,8 +71,9 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "authorize:pkp": "node scripts/authorize-pkp-actions.js",
-    "lint": "eslint src --ext .ts && npm run lint:server-boundary",
+    "lint": "eslint src --ext .ts && npm run lint:server-boundary && npm run lint:sign-guard",
     "lint:server-boundary": "node scripts/check-pkp-mint-server-imports.mjs",
+    "lint:sign-guard": "node scripts/check-sign-guard-imports.mjs",
     "clean": "rm -rf dist && rm -rf browser/dist"
   },
   "keywords": [
@@ -88,7 +94,7 @@
   "sideEffects": false,
   "dependencies": {
     "@gvnrdao/dh-lit-actions": "^0.0.322",
-    "@gvnrdao/dh-lit-ops": "^0.0.315",
+    "@gvnrdao/dh-lit-ops": "^0.0.316",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",
@@ -131,5 +137,21 @@
   "bugs": {
     "url": "https://github.com/gvnrdao/diamond-hands/issues"
   },
-  "homepage": "https://diamond-hands-protocol.com"
+  "homepage": "https://diamond-hands-protocol.com",
+  "typesVersions": {
+    "*": {
+      "server": [
+        "./dist/server.d.ts"
+      ],
+      "deployments": [
+        "./dist/deployments.d.ts"
+      ],
+      "safe-delegation": [
+        "./dist/safe-delegation.d.ts"
+      ],
+      "sign-guard": [
+        "./dist/sign-guard.d.ts"
+      ]
+    }
+  }
 }