IAddressValidity

Assert whether a string represents a valid address on an external blockchain.

Sourced from IAddressValidity.sol on GitHub.

Overview

The IAddressValidity interface enables smart contracts to verify if a given string is a valid address on supported external blockchains. This attestation provides standardized representations of addresses across different chains, facilitating cross-chain operations within the Flare ecosystem.

Supported Chains

Network Type	Supported Chains
Mainnet	BTC (Bitcoin), DOGE (Dogecoin), XRP (XRP Ledger)
Testnet	testBTC (Bitcoin Testnet v3), testDOGE, testXRP

Structs

Request

Toplevel request structure.

struct Request {
    bytes32 attestationType;
    bytes32 sourceId;
    bytes32 messageIntegrityCode;
    RequestBody requestBody;
}

Parameters

• attestationType: ID of the attestation type (0x05 for AddressValidity)
• sourceId: ID of the data source (e.g., BTC, DOGE, XRP)
• messageIntegrityCode: MessageIntegrityCode derived from the expected response
• requestBody: Data defining the request

Response

Toplevel response structure.

struct Response {
    bytes32 attestationType;
    bytes32 sourceId;
    uint64 votingRound;
    uint64 lowestUsedTimestamp;
    RequestBody requestBody;
    ResponseBody responseBody;
}

Parameters

• attestationType: Extracted from the request
• sourceId: Extracted from the request
• votingRound: The ID of the State Connector round in which the request was considered
• lowestUsedTimestamp: The lowest timestamp used to generate the response
• requestBody: Extracted from the request
• responseBody: Data defining the response

Proof

Toplevel proof structure for verification.

struct Proof {
    bytes32[] merkleProof;
    Response data;
}

Parameters

• merkleProof: Merkle proof corresponding to the attestation response
• data: Attestation response

RequestBody

Request body specific to address validity.

struct RequestBody {
    string addressStr;
}

Parameters

• addressStr: Address string to be verified

ResponseBody

Response body specific to address validity.

struct ResponseBody {
    bool isValid;
    string standardAddress;
    bytes32 standardAddressHash;
}

Parameters

• isValid: Boolean indicator of the address validity
• standardAddress: If valid, the standard form of the address; otherwise an empty string
• standardAddressHash: If valid, the standard address hash; otherwise a zero bytes32 string

Chain-Specific Address Formats

Bitcoin (BTC)

• Supports P2PKH, P2SH, P2WPKH, P2WSH, and P2TR addresses
• Bech32 and Bech32m encoding for SegWit addresses
• Legacy addresses with Base58Check encoding

Dogecoin (DOGE)

• Supports P2PKH and P2SH addresses
• Base58Check encoding
• Different address prefixes than Bitcoin

XRP Ledger (XRPL)

• Base58 encoding with checksum
• Addresses typically start with "r"
• Supports X-addresses for destination tags

Implementation Notes

• The attestation ID for AddressValidity is 0x05
• The lowestUsedTimestamp value is 0xffffffffffffffff (maximum 64-bit value)
• For invalid addresses, standardAddress will be empty and standardAddressHash will be zero
• The standardAddressHash is computed using keccak256 on the standardized address string

Usage Example

AddressVerifier.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.25;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
import {IFdcVerification} from "@flarenetwork/flare-periphery-contracts/coston2/IFdcVerification.sol";
import {IAddressValidity} from "@flarenetwork/flare-periphery-contracts/coston2/IAddressValidity.sol";

contract AddressVerifier {
    // On-chain business logic: stores the verification status of an address string.
    mapping(string => bool) public isAddressVerified;

    event AddressVerified(
        string indexed addressStr,
        string standardAddress,
        bytes32 standardAddressHash
    );

    function processAddressProof(
        IAddressValidity.Proof calldata _proof
    ) external {
        // 1. FDC Logic: Verify the proof's authenticity with the Flare network.
        require(isProofValid(_proof), "Invalid address validity proof");

        // 2. Business Logic: Execute actions based on the verified proof data.
        bool isValid = _proof.data.responseBody.isValid;
        string calldata originalAddress = _proof.data.requestBody.addressStr;

        // Only take action if the FDC confirms the address is valid.
        if (isValid) {
            // Take action: update state and emit an event.
            isAddressVerified[originalAddress] = true;

            emit AddressVerified(
                originalAddress,
                _proof.data.responseBody.standardAddress,
                _proof.data.responseBody.standardAddressHash
            );
        }
    }

    function isProofValid(
        IAddressValidity.Proof memory _proof
    ) public view returns (bool) {
        IFdcVerification fdcVerification = ContractRegistry
            .getFdcVerification();
        return fdcVerification.verifyAddressValidity(_proof);
    }
}

Open example in Remix