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 responserequestBody
: 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 requestsourceId
: Extracted from the requestvotingRound
: The ID of the State Connector round in which the request was consideredlowestUsedTimestamp
: The lowest timestamp used to generate the responserequestBody
: Extracted from the requestresponseBody
: Data defining the response
Proof
Toplevel proof structure for verification.
struct Proof {
bytes32[] merkleProof;
Response data;
}
Parameters
merkleProof
: Merkle proof corresponding to the attestation responsedata
: 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 validitystandardAddress
: If valid, the standard form of the address; otherwise an empty stringstandardAddressHash
: 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 is0xffffffffffffffff
(maximum 64-bit value) - For invalid addresses,
standardAddress
will be empty andstandardAddressHash
will be zero - The
standardAddressHash
is computed usingkeccak256
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);
}
}