Verify API

Verify API is a security-focused feature that allows wallets to notify end-users when they may be connecting to a suspicious or malicious domain, helping to prevent phishing attacks across the industry. Once a wallet knows whether an end-user is on uniswap.com or eviluniswap.com, it can help them to detect potentially harmful connections through Verify's combined offering of WalletConnect’s domain registry and Blowfish's domain scanner. For those looking to enable Verify on the app side, check out our reference guide here.

When a user initiates a connection with an application, Verify API enables wallets to present their users with four key states that can help them determine whether the domain they’re about to connect to might be malicious.

These are:

Disclaimer

Verify API is not designed to be bulletproof but to make the impersonation attack harder and require a somewhat sophisticated attacker. We are working on a new standard with various partners to close those gaps and make it bulletproof.

Domain risk detection

The Verify security system will discriminate session proposals & session requests with distinct validations that can be either VALID, INVALID or UNKNOWN.

• Domain match: The domain linked to this request has been verified as this application's domain.
  • This interface appears when the domain a user is attempting to connect to has been ‘verified’ in our domain registry as the registered domain of the application the user is trying to connect to, and the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of VALID.
• Unverified: The domain sending the request cannot be verified.
  • This interface appears when the domain a user is attempting to connect to has not been verified in our domain registry, but the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of UNKNOWN.
• Mismatch: The application's domain doesn't match the sender of this request.
  • This interface appears when the domain a user is attempting to connect to has been flagged as a different domain to the one this application has verified in our domain registry, but the domain has not returned as suspicious from either of the security tools we work with. The verifyContext included in the request will have a validation of INVALID
• Threat: This domain is flagged as malicious and potentially harmful.
  • This interface appears when the domain a user is attempting to connect to has been flagged as malicious on one or more of the security tools we work with. The verifyContext included in the request will contain parameter isScam with value true.

Implementation

Web

To check the Verify API validations and whether or not your user is interacting with potentially malicious app, you can do so by accessing the verifyContext included in the request payload.

...
web3wallet.on("auth_request", async (authRequest) => {
  const { verifyContext } = authRequest
  const validation = verifyContext.verified.validation // can be VALID, INVALID or UNKNOWN
  const origin = verifyContext.verified.origin // the actual verified origin of the request
  const isScam = verifyContext.verified.isScam // true if the domain is flagged as malicious

  // if the domain is flagged as malicious, you should warn the user as they may lose their funds - check the `Threat` case for more info
  if(isScam) {
    // show a warning screen to the user
    // and proceed only if the user accepts the risk
  }

  switch(validation) {
    case "VALID":
      // proceed with the request - check the `Domain match` case for more info
      break
    case "INVALID":
      // show a warning dialog to the user - check the `Mismatch` case for more info
      // and proceed only if the user accepts the risk
      break
    case "UNKNOWN":
      // show a warning dialog to the user - check the `Unverified` case for more info
      // and proceed only if the user accepts the risk
      break
  }

  // respond to the request after the user has approved the request
  await web3wallet.respondAuthRequest(...)
})

For live demo examples of the intended Verify API flows, check out our demo apps:

• Demo Wallet
• Demo App - you can toggle between the verify states by clicking on the gear & selecting the decided Validation before connecting to the wallet
• Demo Malicious App - this app is flagged as malicious and will have the isScam parameter set to true in the verifyContext of the request

iOS

VerifyContext provides a domain verification information about Session.Proposal and Request and is relevant to the verifyDapp function.

It consists of origin of an app from where the request has been sent, validation enum that says whether origin is unknown, valid or invalid and verify URL server.

public struct VerifyContext: Equatable, Hashable {
   public enum ValidationStatus {
       case unknown
       case valid
       case invalid
   }

   public let origin: String?
   public let validation: ValidationStatus
   public let verifyUrl: String
}

Android

Wallet.Event.VerifyContext provides a domain verification information about SessionProposal, SessionRequest and AuthRequest.

It consists of origin of an app from where the request has been sent, validation Enum that says whether origin is VALID, INVALID or UNKNOWN and verify url server.

data class VerifyContext(
    val id: Long,
    val origin: String,
    val validation: Model.Validation,
    val verifyUrl: String
)

enum class Validation {
    VALID, INVALID, UNKNOWN
}

Flutter

WalletConnectSharp.Core.Models.Verify.VerifiedContext provides a domain verification information about SessionProposal, SessionRequest and AuthRequest.

It consists of origin of an app from where the request has been sent, validation Enum that says whether origin is VALID, INVALID or UNKNOWN and verify url server.

public class VerifiedContext
{
    [JsonProperty("origin")]
    public string Origin;

    [JsonProperty("validation")]
    private string _validation;

    public string ValidationString => _validation;

    public Validation Validation
    {
        get
        {
            return FromString();
        }
        set
        {

            _validation = AsString(value);
        }
    }

    [JsonProperty("verifyUrl")]
    public string VerifyUrl { get; set; }

    private Validation FromString()
    {
        switch (ValidationString.ToLowerInvariant())
        {
            case "VALID":
                return Validation.Valid;
            case "INVALID":
                return Validation.Invalid;
            default:
                return Validation.Unknown;
        }
    }

    private string AsString(Validation str)
    {
        switch (str)
        {
            case Validation.Invalid:
                return "INVALID";
            case Validation.Valid:
                return "VALID";
            default:
                return "UNKNOWN";
        }
    }
}

public enum Validation
{
    Unknown,
    Valid,
    Invalid,
}

React Native

To check the Verify API validations and whether or not your user is interacting with potentially malicious dapp, you can do so by accessing the verifyContext included in the SessionProposalEvent:

_web3Wallet!.onSessionProposal.subscribe((SessionProposalEvent? args) {
  if (args != null) {
    final scamApp = args.verifyContext?.validation.scam;
    final invalidApp = args.verifyContext?.validation.invalid;
    final validApp = args.verifyContext?.validation.valid;
    final unknown = args.verifyContext?.validation.unknown;
  }
});

C#

To check the Verify API validations and whether or not your user is interacting with potentially malicious app, you can do so by accessing the verifyContext included in the request payload.

...
web3wallet.on("auth_request", async (authRequest) => {
  const { verifyContext } = authRequest
  const validation = verifyContext.verified.validation // can be VALID, INVALID or UNKNOWN
  const origin = verifyContext.verified.origin // the actual verified origin of the request
  const isScam = verifyContext.verified.isScam // true if the domain is flagged as malicious

  // if the domain is flagged as malicious, you should warn the user as they may lose their funds - check the `Threat` case for more info
  if(isScam) {
    // show a warning screen to the user
    // and proceed only if the user accepts the risk
  }

  switch(validation) {
    case "VALID":
      // proceed with the request - check the `Domain match` case for more info
      break
    case "INVALID":
      // show a warning dialog to the user - check the `Mismatch` case for more info
      // and proceed only if the user accepts the risk
      break
    case "UNKNOWN":
      // show a warning dialog to the user - check the `Unverified` case for more info
      // and proceed only if the user accepts the risk
      break
  }

  // respond to the request after the user has approved the request
  await web3wallet.respondAuthRequest(...)
})

For live demo examples of the intended Verify API flows, check out our demo apps:

• Demo Web Wallet
• Demo React Native Wallet
• Demo App - you can toggle between the verify states by clicking on the gear & selecting the decided Validation before connecting to the wallet
• Demo Malicious App - this app is flagged as malicious and will have the isScam parameter set to true in the verifyContext of the request