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

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

import "@flare-foundation/flare-smart-contracts-v2/contracts/userInterfaces/IFdcHub.sol";
import "@flare-foundation/flare-smart-contracts-v2/contracts/userInterfaces/IFdcVerification.sol";
import "@flare-foundation/flare-smart-contracts-v2/contracts/userInterfaces/fdc/IAddressValidity.sol";

contract AddressVerifier {
    IFdcHub private fdcHub;
    IFdcVerification private fdcVerification;

    bytes32 private constant ATTESTATION_TYPE_ADDRESS_VALIDITY = 0x0500000000000000000000000000000000000000000000000000000000000000;
    bytes32 private constant SOURCE_ID_BTC = 0x4254430000000000000000000000000000000000000000000000000000000000;

    constructor(address _fdcHubAddress, address _fdcVerificationAddress) {
        fdcHub = IFdcHub(_fdcHubAddress);
        fdcVerification = IFdcVerification(_fdcVerificationAddress);
    }

    // Request address validation
    function requestAddressValidation(string calldata _address) external payable {
        // Create request body
        IAddressValidity.RequestBody memory requestBody = IAddressValidity.RequestBody({
            addressStr: _address
        });

        // Encode the full request
        bytes memory encodedRequest = abi.encode(
            ATTESTATION_TYPE_ADDRESS_VALIDITY,
            SOURCE_ID_BTC,
            bytes32(0), // messageIntegrityCode (would need to be calculated properly)
            requestBody
        );

        // Submit the request with payment
        fdcHub.requestAttestation{value: msg.value}(encodedRequest);
    }

    // Verify a provided proof
    function verifyAddressProof(IAddressValidity.Proof calldata _proof) external view returns (
        bool isValid,
        string memory standardAddress,
        bytes32 standardAddressHash
    ) {
        // Verify the proof using FdcVerification
        bool proofVerified = fdcVerification.verifyAddressValidity(_proof);

        if (proofVerified) {
            // Extract data from the verified proof
            isValid = _proof.data.responseBody.isValid;
            standardAddress = _proof.data.responseBody.standardAddress;
            standardAddressHash = _proof.data.responseBody.standardAddressHash;
        }

        return (isValid, standardAddress, standardAddressHash);
    }
}