ox
Version:
154 lines • 4.43 kB
JavaScript
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';
import * as TempoAddress from './TempoAddress.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 {
constructor({ address }) {
super(`Address "${address}" does not contain the TIP-1022 virtual address marker.`);
Object.defineProperty(this, "name", {
enumerable: true,
configurable: true,
writable: true,
value: 'VirtualAddress.InvalidMagicError'
});
}
}
function resolveAddress(address) {
const resolved = TempoAddress.resolve(address);
Address.assert(resolved, { strict: false });
return resolved;
}
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