@vultisig/core-chain 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @vultisig/core-chain
 
+## 2.21.0
+
+### Minor Changes
+
+- [#912](https://github.com/vultisig/vultisig-sdk/pull/912) [`403d5d5`](https://github.com/vultisig/vultisig-sdk/commit/403d5d5f7c7dba3e45cb818899db00f765541ecf) Thanks [@Ehsan-saradar](https://github.com/Ehsan-saradar)! - feat(solana): validator-metadata seam (Stakewiz, swappable)
+
+  Phase 2 of Solana native staking. Adds a swappable off-chain enrichment seam for
+  validator display metadata (name / logo / APY estimate / score) on top of the
+  Phase 1 on-chain `getVoteAccounts` rows, under
+  `@vultisig/core-chain/chains/solana/staking/metadata`:
+
+  - `ValidatorMetadataProvider` — provider interface; contract: never throws.
+  - `stakewizProvider` — concrete impl over api.stakewiz.com (`apy_estimate`
+    percent→fraction, `image`→logo, `wiz_score`→score). Degrades to an empty map
+    on any outage / non-OK / parse error so callers fall back to on-chain-only.
+  - `enrichValidators` — merges the metadata map onto the validator rows; the
+    provider is injectable for tests.
+
 ## 2.20.0
 
 ### Minor Changes

package/dist/chains/solana/staking/metadata/ValidatorMetadataProvider.d.ts

@@ -0,0 +1,25 @@
+import { ValidatorMetadata } from '../models/validator.js';
+/**
+ * Swappable seam for off-chain validator enrichment (name / logo / APY /
+ * score). The core stake/commission/activation data comes from the on-chain
+ * `getVoteAccounts` read; this interface only supplies display metadata, which
+ * is the part most likely to change source (Stakewiz today, validators.app or
+ * an in-house endpoint tomorrow). Keeping it behind an interface lets the picker
+ * and views stay independent of any single provider.
+ *
+ * Contract: implementations MUST NOT throw on a provider outage. A failed or
+ * rate-limited source returns a partial or empty map so callers degrade
+ * gracefully — falling back to a truncated vote pubkey and the on-chain
+ * commission, with no logo, never a crash.
+ *
+ * Port of iOS `ValidatorMetadataProvider`.
+ */
+export type ValidatorMetadataProvider = {
+    /**
+     * Returns metadata keyed by vote pubkey for the requested validators. The
+     * returned map may be empty or cover only a subset of the input — a validator
+     * absent from the map simply has no enrichment available. Never throws.
+     */
+    metadata: (votePubkeys: string[]) => Promise<Record<string, ValidatorMetadata>>;
+};
+//# sourceMappingURL=ValidatorMetadataProvider.d.ts.map

package/dist/chains/solana/staking/metadata/ValidatorMetadataProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidatorMetadataProvider.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/ValidatorMetadataProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAEvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAChF,CAAA"}

package/dist/chains/solana/staking/metadata/ValidatorMetadataProvider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ValidatorMetadataProvider.js.map

package/dist/chains/solana/staking/metadata/ValidatorMetadataProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidatorMetadataProvider.js","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/ValidatorMetadataProvider.ts"],"names":[],"mappings":""}

package/dist/chains/solana/staking/metadata/enrichValidators.d.ts

@@ -0,0 +1,13 @@
+import { SolanaValidator } from '../models/validator.js';
+import { ValidatorMetadataProvider } from './ValidatorMetadataProvider.js';
+/**
+ * Merges off-chain metadata (name / logo / APY) onto on-chain validator rows
+ * via the swappable provider. The provider never throws — on an outage the rows
+ * pass through with empty metadata and the display layer falls back to a
+ * truncated vote pubkey + on-chain commission.
+ *
+ * Replaces the call site where iOS's view models invoke the
+ * `ValidatorMetadataProvider`; the provider is injectable for tests.
+ */
+export declare const enrichValidatorsWithMetadata: (validators: SolanaValidator[], provider?: ValidatorMetadataProvider) => Promise<SolanaValidator[]>;
+//# sourceMappingURL=enrichValidators.d.ts.map

package/dist/chains/solana/staking/metadata/enrichValidators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichValidators.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/enrichValidators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACvC,YAAY,eAAe,EAAE,EAC7B,WAAU,yBAA6D,KACtE,OAAO,CAAC,eAAe,EAAE,CAM3B,CAAA"}

package/dist/chains/solana/staking/metadata/enrichValidators.js

@@ -0,0 +1,18 @@
+import { stakewizValidatorMetadataProvider } from './stakewizProvider.js';
+/**
+ * Merges off-chain metadata (name / logo / APY) onto on-chain validator rows
+ * via the swappable provider. The provider never throws — on an outage the rows
+ * pass through with empty metadata and the display layer falls back to a
+ * truncated vote pubkey + on-chain commission.
+ *
+ * Replaces the call site where iOS's view models invoke the
+ * `ValidatorMetadataProvider`; the provider is injectable for tests.
+ */
+export const enrichValidatorsWithMetadata = async (validators, provider = stakewizValidatorMetadataProvider) => {
+    const metadataByVotePubkey = await provider.metadata(validators.map(v => v.votePubkey));
+    return validators.map(validator => {
+        const metadata = metadataByVotePubkey[validator.votePubkey];
+        return metadata ? { ...validator, metadata } : validator;
+    });
+};
+//# sourceMappingURL=enrichValidators.js.map

package/dist/chains/solana/staking/metadata/enrichValidators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichValidators.js","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/enrichValidators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAA;AAGtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,EAC/C,UAA6B,EAC7B,WAAsC,iCAAiC,EAC3C,EAAE;IAC9B,MAAM,oBAAoB,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;IACvF,OAAO,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;QAChC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QAC3D,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/chains/solana/staking/metadata/stakewizProvider.d.ts

@@ -0,0 +1,3 @@
+import { ValidatorMetadataProvider } from './ValidatorMetadataProvider.js';
+export declare const stakewizValidatorMetadataProvider: ValidatorMetadataProvider;
+//# sourceMappingURL=stakewizProvider.d.ts.map

package/dist/chains/solana/staking/metadata/stakewizProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stakewizProvider.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/stakewizProvider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAmDvE,eAAO,MAAM,iCAAiC,EAAE,yBAoC/C,CAAA"}

package/dist/chains/solana/staking/metadata/stakewizProvider.js

@@ -0,0 +1,73 @@
+import { attempt } from '@vultisig/lib-utils/attempt';
+/**
+ * Concrete `ValidatorMetadataProvider` backed by Stakewiz
+ * (https://api.stakewiz.com). The `/validators` endpoint returns the full
+ * validator set in one response, so a single fetch enriches an arbitrary batch
+ * of vote pubkeys. A failed or rate-limited fetch yields an empty map — the
+ * call never throws, so callers degrade to on-chain-only display. The ~1h cache
+ * is handled by the consuming react-query hook's `staleTime`.
+ *
+ * Field mapping (Stakewiz → ValidatorMetadata):
+ *   name          → name
+ *   image         → logoUrl
+ *   apy_estimate  → apyEstimate  (percent on the wire, stored as a fraction)
+ *   wiz_score     → score
+ *
+ * Port of iOS `StakewizValidatorMetadataProvider`.
+ */
+const stakewizValidatorsUrl = 'https://api.stakewiz.com/validators';
+const asTrimmedString = (value) => typeof value === 'string' ? value.trim() || undefined : undefined;
+const asFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/**
+ * Stakewiz reports `apy_estimate` as a percentage (e.g. 5.72) — store as a
+ * fraction. A genuine `0` is preserved (0% APY ≠ "no APY"); only missing /
+ * non-finite / negative values collapse to `undefined`.
+ */
+const apyFraction = (percent) => {
+    const value = asFiniteNumber(percent);
+    return value !== undefined && value >= 0 ? value / 100 : undefined;
+};
+const toMetadata = (row) => {
+    const wizScore = asFiniteNumber(row.wiz_score);
+    return {
+        name: asTrimmedString(row.name),
+        logoUrl: asTrimmedString(row.image),
+        apyEstimate: apyFraction(row.apy_estimate),
+        score: wizScore === undefined ? undefined : Math.round(wizScore),
+    };
+};
+export const stakewizValidatorMetadataProvider = {
+    metadata: async (votePubkeys) => {
+        const requested = new Set(votePubkeys.filter(Boolean));
+        if (requested.size === 0) {
+            return {};
+        }
+        const result = await attempt(async () => {
+            const response = await fetch(stakewizValidatorsUrl, {
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                throw new Error(`Stakewiz responded ${response.status}`);
+            }
+            return (await response.json());
+        });
+        // Outage / rate-limit / malformed response — degrade to on-chain-only.
+        if ('error' in result || !Array.isArray(result.data)) {
+            return {};
+        }
+        const map = {};
+        for (const row of result.data) {
+            // Skip malformed elements (`null`, primitives, missing/invalid pubkey)
+            // rather than letting a field access throw — the never-throw contract.
+            if (typeof row !== 'object' || row === null) {
+                continue;
+            }
+            const votePubkey = asTrimmedString(row.vote_identity);
+            if (votePubkey && requested.has(votePubkey)) {
+                map[votePubkey] = toMetadata(row);
+            }
+        }
+        return map;
+    },
+};
+//# sourceMappingURL=stakewizProvider.js.map

package/dist/chains/solana/staking/metadata/stakewizProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stakewizProvider.js","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/staking/metadata/stakewizProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vultisig/core-chain",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Blockchain chain logic shared across Vultisig clients",
   "license": "MIT",
   "repository": {
@@ -690,6 +690,21 @@
       "import": "./dist/chains/solana/staking/cooldownGate.js",
       "default": "./dist/chains/solana/staking/cooldownGate.js"
     },
+    "./chains/solana/staking/metadata/enrichValidators": {
+      "types": "./dist/chains/solana/staking/metadata/enrichValidators.d.ts",
+      "import": "./dist/chains/solana/staking/metadata/enrichValidators.js",
+      "default": "./dist/chains/solana/staking/metadata/enrichValidators.js"
+    },
+    "./chains/solana/staking/metadata/stakewizProvider": {
+      "types": "./dist/chains/solana/staking/metadata/stakewizProvider.d.ts",
+      "import": "./dist/chains/solana/staking/metadata/stakewizProvider.js",
+      "default": "./dist/chains/solana/staking/metadata/stakewizProvider.js"
+    },
+    "./chains/solana/staking/metadata/ValidatorMetadataProvider": {
+      "types": "./dist/chains/solana/staking/metadata/ValidatorMetadataProvider.d.ts",
+      "import": "./dist/chains/solana/staking/metadata/ValidatorMetadataProvider.js",
+      "default": "./dist/chains/solana/staking/metadata/ValidatorMetadataProvider.js"
+    },
     "./chains/solana/staking/models/stakeAccount": {
       "types": "./dist/chains/solana/staking/models/stakeAccount.d.ts",
       "import": "./dist/chains/solana/staking/models/stakeAccount.js",
@@ -1994,7 +2009,7 @@
     "@cosmjs/proto-signing": "^0.39.0",
     "@cosmjs/stargate": "^0.39.0",
     "@lifi/sdk": "^4.0.0",
-    "@mysten/sui": "^2.19.0",
+    "@mysten/sui": "^2.20.1",
     "@noble/hashes": "^1.8.0",
     "@polkadot/api": "^16.5.6",
     "@polkadot/util": "^14.0.3",
@@ -2014,7 +2029,7 @@
     "date-fns": "^4.4.0",
     "ethers": "^6.17.0",
     "tiny-secp256k1": "^2.2.4",
-    "viem": "^2.52.2",
+    "viem": "^2.53.1",
     "xrpl": "^5.0.0"
   }
 }