ox/dist/tempo/VirtualAddress.js

Ethereum Standard Library

import * as Address from '../core/Address.js';
import * as Bytes from '../core/Bytes.js';
import * as Errors from '../core/Errors.js';
import * as Hex from '../core/Hex.js';
/** Fixed 10-byte marker used by TIP-1022 virtual addresses. */
export const magic = '0xfdfdfdfdfdfdfdfdfdfd';
/**
 * Builds a TIP-1022 virtual address from a `masterId` and `userTag`.
 *
 * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
 *
 * TIP-1022 encodes virtual addresses as:
 * `[4-byte masterId][10-byte VIRTUAL_MAGIC][6-byte userTag]`
 *
 * @example
 * ```ts twoslash
 * import { VirtualAddress } from 'ox/tempo'
 *
 * const address = VirtualAddress.from({
 *   masterId: '0x58e21090',
 *   userTag: '0x010203040506'
 * })
 *
 * address
 * // @log: '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
 * ```
 *
 * @param value - The virtual address parts.
 * @returns The virtual address.
 */
export function from(value) {
    return Address.from(Hex.concat(toFixedHex(value.masterId, 4), magic, toFixedHex(value.userTag, 6)));
}
/**
 * Checks whether an address matches the TIP-1022 virtual address format.
 *
 * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
 *
 * This only checks the reserved byte layout, not whether the `masterId`
 * is registered onchain.
 *
 * @example
 * ```ts twoslash
 * import { VirtualAddress } from 'ox/tempo'
 *
 * const isVirtual = VirtualAddress.isVirtual(
 *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
 * )
 *
 * isVirtual
 * // @log: true
 * ```
 *
 * @param address - Address to check.
 * @returns `true` if the address matches the virtual-address layout.
 */
export function isVirtual(address) {
    try {
        const resolved = resolveAddress(address);
        return Hex.slice(resolved, 4, 14).toLowerCase() === magic;
    }
    catch {
        return false;
    }
}
/**
 * Parses a TIP-1022 virtual address into its `masterId` and `userTag` parts.
 *
 * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
 *
 * @example
 * ```ts twoslash
 * import { VirtualAddress } from 'ox/tempo'
 *
 * const parsed = VirtualAddress.parse(
 *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
 * )
 *
 * parsed
 * // @log: { masterId: '0x58e21090', userTag: '0x010203040506' }
 * ```
 *
 * @param address - The virtual address to parse.
 * @returns The decoded virtual address components.
 */
export function parse(address) {
    const resolved = resolveAddress(address);
    if (Hex.slice(resolved, 4, 14).toLowerCase() !== magic)
        throw new InvalidMagicError({ address: resolved });
    return {
        masterId: Hex.slice(resolved, 0, 4),
        userTag: Hex.slice(resolved, 14, 20),
    };
}
/**
 * Validates that an address matches the TIP-1022 virtual address format.
 *
 * [TIP-1022](https://docs.tempo.xyz/protocol/tips/tip-1022)
 *
 * This only validates the reserved byte layout, not whether the `masterId`
 * resolves to a registered master onchain.
 *
 * @example
 * ```ts twoslash
 * import { VirtualAddress } from 'ox/tempo'
 *
 * const valid = VirtualAddress.validate(
 *   '0x58e21090fdfdfdfdfdfdfdfdfdfd010203040506'
 * )
 *
 * valid
 * // @log: true
 * ```
 *
 * @param address - Address to validate.
 * @returns `true` if the address has a valid virtual-address layout.
 */
export function validate(address) {
    try {
        parse(address);
        return true;
    }
    catch {
        return false;
    }
}
/** Thrown when an address does not contain the TIP-1022 virtual marker. */
export class InvalidMagicError extends Errors.BaseError {
    name = 'VirtualAddress.InvalidMagicError';
    constructor({ address }) {
        super(`Address "${address}" does not contain the TIP-1022 virtual address marker.`);
    }
}
function resolveAddress(address) {
    const resolved = address;
    Address.assert(resolved, { strict: false });
    return resolved;
}
/**
 * Converts a virtual address {@link Part} to a zero-padded hex string of the
 * given byte size. Branches by input type so that bytes inputs avoid the
 * `number -> hex -> bytes -> hex` round trip the audit called out.
 *
 * @internal
 */
function toFixedHex(value, size) {
    if (typeof value === 'number' || typeof value === 'bigint')
        return Hex.fromNumber(value, { size });
    if (typeof value === 'string') {
        Hex.assert(value, { strict: true });
        return Hex.padLeft(value, size);
    }
    return Hex.fromBytes(Bytes.padLeft(value, size));
}
//# sourceMappingURL=VirtualAddress.js.map