Proposal: Wallet Security Risk Detection & Policy Mechanism

[svein1010]

Wallet Security Risk Detection & Policy Mechanism Proposal

Abstract

This proposal introduces a security strategy to detect and mitigate risks associated with compromised or vulnerable wallet versions. By checking a remote configuration during the connect() phase, the adapter can warn users or block connections to wallets known to have critical security flaws (e.g., private key leakage).

Motivation

Background

With the rapid expansion of the Web3 ecosystem, the number of wallets continues to grow, release cycles are accelerating, and technology stacks are becoming increasingly diverse. Inevitably, certain versions of some wallets may exhibit security vulnerabilities in the future (such as irregular signing processes or inconsistent behavior). It is therefore necessary to proactively establish a risk identification and response mechanism, along with a security framework, to prevent such potential risks from being amplified within the ecosystem.

Goal

To further enhance security and establish a fully community-driven defense model, we propose introducing a proactive security mechanism at the adapter layer. By empowering the community to autonomously define and enforce security policies, this framework enables a collective response to emergency risks. Through this dynamic, community-governed multi-layer framework, the adapter evolves from a passive connection component into an "intelligent gateway" with shared security awareness. This mechanism delivers three key benefits:

Community Governance: Enhance the overall ecosystem credibility through transparent, community-led oversight.

Risk Isolation: Rapidly identify and isolate wallet versions with known issues based on community consensus, ensuring that all DApps using the adapter receive immediate and consistent protection.

Unified Policy Layer: Abstract security governance logic away from individual DApps, unifying it into a configurable policy layer maintained by the community. This reduces integration costs while improving the long-term maintainability of the system.

Proposed Solution

1. Workflow

1. When the adapter is instantiated, it fetches a security configuration JSON (defaulting to a community-maintained list or a developer-specified URL).
2. When adapter.connect() is called, it checks the current wallet's version against the risk list.
3. If a risk is detected:
   • Trigger a customizable onRiskDetected callback.
   • If no callback is provided, default behavior (e.g., throw an error or warn) applies.
4. Caching: Configuration is cached for 10 minutes to minimize network overhead.

2. Configuration Schema (Remote JSON)

The configuration file will be hosted remotely (e.g., GitHub Pages or S3).

{
  "v": "1.0",
  "ts": 1777356472528,
  "wallets": {
    "walletA": [
      {
        "noticeType": 1,
        "title": "risk1",
        "ext": ">=4.1.0 <4.2.0",
        "ios": ">=4.1.0 <4.2.0",
        "and": ">=4.1.0 <4.2.0"
      }
    ],
    "walletB": [
      {
        "noticeType": 3,
        "title": "risk2",
        "ext": ">=2.2.0 <3.1.0",
        "ios": ">=2.2.0 <3.1.0",
        "and": ">=2.2.0 <3.1.0"
      }
    ]
  }
}

Fields:

Field name	Type	Description
v	string	Security config version
ts	number	Last-updated timestamp of the config, in milliseconds
wallets.{WalletName}	Array<RiskConfig>	Risk entries for the wallet; present when at least one risk is registered
riskConfig.noticeType	number	1: Low risk, user only notified. 2: High risk, pop-up reminder and the adapter is blocked for this wallet version. 3: Critical risk, the adapter will be removed.
riskConfig.title	string	Risk description
riskConfig.ext	string	Semver range of wallet extension versions affected by the risk (Optional)
riskConfig.ios	string	Semver range of wallet iOS app versions affected by the risk (Optional)
riskConfig.and	string	Semver range of wallet Android app versions affected by the risk (Optional)

Interface

See the full TypeScript interface definitions in the Interface section below.

3. API Design & Usage Examples

1. Basic Usage (Default)
   By default, the adapter does not perform security checks. DApp developers should enable the check and provide a remote configuration URL:

const adapter = new WalletAdapter({
  securityOptions: {
    enabled: true,
    configUrls: ['https://your-domain.com/security-config.json'],
  },
});

// connect() automatically performs the security check
await adapter.connect();

Note: configUrls accepts an array; the adapter merges all fetched configs.

2. Custom Handling Logic (Callback)
   Developers can intercept the risk event to show custom UI (e.g., modals or toasts) instead of the default error.

const adapter = new WalletAdapter({
  securityOptions: {
    onRiskDetected: async (result) => {
      console.error('Security risk detection result:', result);

      // Example: Show a custom confirmation dialog to the user
      const risk = result.risks[0];
      const userConfirmed = await showWarningModal({
        title: `Security Alert`,
        message: `Risk detected: ${risk.title} (noticeType ${risk.noticeType}). Do you still want to connect?`,
      });

      if (!userConfirmed) {
        throw new Error('User declined connection due to security risk.');
      }
      // If the user confirms, the connection process continues
    },
  },
});

await adapter.connect();

3. Set the request timeout
   Sets the timeout for the security config request. Default: 2000ms.

const adapter = new WalletAdapter({
  securityOptions: {
    timeout: 3000,
  },
});

4. Configure the number of retries when the request fails
   Defaults to 0. When set to a value greater than 0, the adapter retries the request that many times on failure.

const adapter = new WalletAdapter({
  securityOptions: {
    retries: 3,
  },
});

5. Configure logic for handling request errors
   Developers can return a custom risk config as a fallback:

const adapter = new WalletAdapter({
  securityOptions: {
    onConfigFallback: () => {
      return {
        v: '1.0',
        ts: Date.now(),
        wallets: {
          ExampleWallet: [
            {
              title: 'risk description',
              noticeType: 1,
              ext: '>=2.2.0 <3.1.0',
            },
          ],
        },
      };
    },
  },
});

Or rethrow the error:

const adapter = new WalletAdapter({
  securityOptions: {
    onConfigFallback: () => {
      throw new Error('Failed to fetch security config.');
    },
  },
});

6. Configure cache duration
   The adapter caches fetched configs for 10 minutes by default. Customize the duration with:

const adapter = new WalletAdapter({
  securityOptions: {
    cacheTTL: 5 * 60 * 1000,
  },
});

Interface

interface Risk {
  title: string;
  noticeType: 1 | 2 | 3;
  ext?: string;
  ios?: string;
  and?: string;
}
interface RiskConfig {
  v: string;
  ts: number;
  wallets: {
    [walletName: string]: Risk[];
  };
}
interface SecurityCheckResult {
  risks: Risk[];
}
export interface SecurityOptions {
  /**
   * Remote config JSON URL(s)
   */
  configUrls?: string[];
  /**
   * Enable security check (default: false)
   */
  enabled?: boolean;
  /**
   * Custom callback when a risk is detected
   */
  onRiskDetected?: (result: SecurityCheckResult) => Promise<void>;
  /**
   * Request timeout in milliseconds (default: 2000)
   */
  timeout?: number;
  /**
   * Number of retries when the config fetch fails (default: 0)
   */
  retries?: number;
  /**
   * Custom fallback handler for config fetch errors
   */
  onConfigFallback?: () => RiskConfig | Promise<RiskConfig>;
  /**
   * Cache duration in milliseconds (default: 10 * 60 * 1000)
   */
  cacheTTL?: number;
}

Implementation Details

1. Fallback Strategy: If the remote config request fails:

• Use cached data if available.
• If no cache exists, default to "Safe" (allow connection) to prevent blocking users due to network issues.

2. Caching: In-memory caching with a TTL of 10 minutes.

Discussion Points

We welcome feedback from the community on the following:

• JSON Schema: Is the proposed schema flexible enough for future extension (e.g., additional platforms)?

• UX: Is a 10-minute cache duration appropriate for balancing security and performance?

[web3iocore]

Security Benefits & Scenario Analysis

It is important to clarify that the adapter itself does not maintain any official wallet risk list, nor does it make governance decisions about which wallets are considered risky.

The adapter only provides a standardized security capability framework.

All security policies are entirely controlled by DApp developers, including:

• Whether to enable the mechanism
• Which configuration source(s) to trust
• Which wallet versions to flag
• Whether to warn or block
• How risks are presented to users

In other words:

Adapter provides the capability
DApps define the policy

This design avoids centralized governance concerns while giving DApps flexible and customizable wallet risk control capabilities.

---

Benefits for DApps

Scenario 1 — Secure DApp, Vulnerable Wallet

DApp: Safe
Wallet: Vulnerable

Examples:

• Incorrect signing behavior
• Transaction display issues
• Approval amount display bugs
• Known wallet security vulnerabilities

Without this mechanism:

Users may assume the DApp caused the loss

even if the actual issue originated from the wallet.

With this mechanism enabled:

DApp defines its own wallet risk rules
 -> Adapter performs checks during connect()
 -> User receives warning or connection is blocked

Benefits for DApps:

• Protect users proactively
• Reduce reputation damage caused by external wallet issues
• Improve overall security credibility
• Add a wallet risk isolation layer

---

Scenario 2 — DApps Supporting Multiple Wallets

Modern DApps often support many wallets simultaneously:

• Browser extensions
• Mobile wallets
• Hardware wallets
• WalletConnect-compatible wallets

Without a shared framework, each DApp must implement:

• Version checks
• Risk matching
• Warning logic
• Retry handling
• Cache management

With this mechanism:

Adapter handles the infrastructure
DApps only configure policies

Benefits for DApps:

• Lower development cost
• Reduced maintenance burden
• Faster integration
• Reusable security infrastructure

The adapter acts as a standardized wallet security middleware layer.

---

Scenario 3 — Different DApps Require Different Security Levels

Different applications have different security requirements.

For example:

DApp Type	Security Requirement
Games	Lower
DeFi	High
Institutional platforms	Very high

This mechanism allows DApps to independently decide:

• Whether to enable checks
• Which config sources to trust
• Which wallets or versions to restrict
• Whether to warn or hard-block

Benefits:

• Full policy flexibility
• No centralized enforcement
• Compatible with internal enterprise security systems
• Allows ecosystem-level customization

Example:

configUrls: [
  'https://security.company.com/wallet-policy.json'
]

This is important because:

The adapter does not act as a centralized governance authority.

---

Benefits for Users

Scenario 4 — User Uses a Vulnerable Wallet Version

Wallet: Vulnerable
DApp: Security mechanism enabled

Most users do not actively follow:

• Security disclosures
• Wallet release notes
• Vulnerability announcements

With this mechanism:

Risk checks occur automatically during connect()

Benefits for users:

• Additional protection without requiring technical knowledge
• Reduced risk of continuing to use vulnerable wallet versions
• Earlier visibility into wallet-related risks
• Lower probability of asset loss

In practice:

The DApp helps take on part of the security responsibility on behalf of users.

---

Scenario 5 — Users Can Choose DApps with Different Security Standards

Because policy control belongs to DApps:

• Conservative DApps may hard-block risky wallets
• Standard DApps may only show warnings
• High-security platforms may use fail-closed strategies

Benefits for users:

• Freedom to choose stricter or more flexible platforms
• Market-driven security competition
• Encourages higher ecosystem security standards

This aligns well with decentralized ecosystem principles:

Different applications can define different trust models.

---

Benefits for Wallets

Scenario 6 — Faster Ecosystem Response to Wallet Incidents

If a wallet vulnerability is discovered:

Traditional flow:

Wallet publishes announcement
 -> DApps and users respond slowly

With this mechanism:

DApps can immediately update their own policies

Benefits for wallets:

• Faster containment of vulnerable versions
• Reduced impact scope
• Faster ecosystem response

Importantly:

Risk handling decisions are made by DApps themselves,
not by the adapter.

---

Scenario 7 — Encourages Better Security Transparency

Over time, wallets with:

• Faster incident response
• Better disclosure processes
• Stronger security practices

will naturally gain greater trust from DApps.

Benefits for wallets:

• Stronger security reputation
• Increased ecosystem trust
• Better alignment with professional security standards

---

Summary

This mechanism should not be viewed as:

A centralized wallet blacklist system

Instead, it is better described as:

A standardized wallet security capability framework

or:

A DApp-driven wallet risk detection infrastructure

In all:

The adapter provides the capability,
while DApps define and control the policy.

[zorro11639]

There are two questions needed to be discussed:

1. The risk config only returns the version range corresponding to the wallet risk. Does the DApps need to obtain the current wallet's environment and version number itself?

2. configUrls is an array. If multiple profiles return different noticeType values ​​for the same wallet version, how should this be handled? Should the highest or lowest level be used?

[zorro11639]

Currently we can adopt the following strategies:

1. First question: For the first version, we can temporarily let users determine the current wallet's environment and version on their own. In a later phase, we will provide environment and version detection methods for each wallet.

2. Second question: The adapter will not perform any merging. All configurations will be passed directly to the DApp via the onRiskDetected callback, and it will be up to the DApp to handle them. In general, this scenario (multiple profiles returning different noticeType values for the same wallet version) is quite rare.

Any other suggestions are welcome.