@beclab/olaresid 0.1.1 → 0.1.3

package/src/utils/olares-id.ts

@@ -0,0 +1,49 @@
+/**
+ * Olares ID Utilities
+ *
+ * Olares ID is a new format that looks like email addresses: user@domain.com
+ * It's essentially a domain name where the first dot (.) is replaced with an at sign (@)
+ *
+ * Examples:
+ *   - alice.example.com → alice@example.com (Olares ID)
+ *   - bob.sub.example.com → bob@sub.example.com (Olares ID)
+ */
+
+/**
+ * Convert Olares ID format to standard domain format
+ * Replaces the first @ with a dot (.)
+ *
+ * @param input The input string (can be either Olares ID or domain format)
+ * @returns The normalized domain format
+ *
+ * @example
+ * normalizeToDomain('alice@example.com') // returns 'alice.example.com'
+ * normalizeToDomain('alice.example.com') // returns 'alice.example.com' (no change)
+ * normalizeToDomain('bob@sub.example.com') // returns 'bob.sub.example.com'
+ */
+export function normalizeToDomain(input: string): string {
+	if (!input) {
+		return input;
+	}
+	// Replace the first @ with a dot
+	return input.replace('@', '.');
+}
+
+/**
+ * Convert standard domain format to Olares ID format
+ * Replaces the first dot (.) with an at sign (@)
+ *
+ * @param domain The domain name
+ * @returns The Olares ID format
+ *
+ * @example
+ * normalizeToOlaresId('alice.example.com') // returns 'alice@example.com'
+ * normalizeToOlaresId('bob.sub.example.com') // returns 'bob@sub.example.com'
+ */
+export function normalizeToOlaresId(domain: string): string {
+	if (!domain) {
+		return domain;
+	}
+	// Replace the first dot with @
+	return domain.replace('.', '@');
+}

package/src/utils/tag-abi-codec.ts

@@ -0,0 +1,158 @@
+import { AbiCoder } from 'ethers';
+
+/**
+ * Tag ABI Codec
+ * Unified encoding/decoding utility for Tag values
+ *
+ * Key Principle: ALL values use abi.encode()
+ * - Simple values: abi.encode("value")
+ * - Arrays: abi.encode(["a", "b", "c"])
+ * - Tuples: abi.encode(struct)
+ * - Elements for push: abi.encode(singleElement)
+ */
+export class TagAbiCodec {
+	private static abiCoder = new AbiCoder();
+
+	/**
+	 * Parse tuple field types from ABI type string
+	 * @param abiType e.g., "tuple(string,uint8,tuple(bool,address))"
+	 * @returns Array of field types: ["string", "uint8", "tuple(bool,address)"]
+	 */
+	private static parseTupleFields(abiType: string): string[] {
+		if (!abiType.startsWith('tuple(')) {
+			return [];
+		}
+
+		const innerTypes = abiType.slice(6, -1); // Remove "tuple(" and ")"
+		const fields: string[] = [];
+		let depth = 0;
+		let currentField = '';
+
+		for (let i = 0; i < innerTypes.length; i++) {
+			const char = innerTypes[i];
+
+			if (char === '(') {
+				depth++;
+				currentField += char;
+			} else if (char === ')') {
+				depth--;
+				currentField += char;
+			} else if (char === ',' && depth === 0) {
+				fields.push(currentField.trim());
+				currentField = '';
+			} else {
+				currentField += char;
+			}
+		}
+
+		if (currentField) {
+			fields.push(currentField.trim());
+		}
+
+		return fields;
+	}
+
+	/**
+	 * Convert object to array based on ABI type structure
+	 * Supports nested tuples recursively
+	 *
+	 * @param abiType ABI type string
+	 * @param value Value (can be object or array)
+	 * @returns Array value
+	 */
+	private static convertObjectToArray(abiType: string, value: any): any {
+		// If already an array or not an object, return as-is
+		if (
+			Array.isArray(value) ||
+			typeof value !== 'object' ||
+			value === null
+		) {
+			return value;
+		}
+
+		// If not a tuple type, return as-is
+		if (!abiType.startsWith('tuple(')) {
+			return value;
+		}
+
+		// Parse tuple field types
+		const fieldTypes = this.parseTupleFields(abiType);
+		const fieldNames = Object.keys(value);
+
+		if (fieldNames.length !== fieldTypes.length) {
+			throw new Error(
+				`Tuple field count mismatch: expected ${
+					fieldTypes.length
+				} fields, got ${fieldNames.length} (${fieldNames.join(', ')})`
+			);
+		}
+
+		// Convert object to array, recursively handling nested tuples
+		const result: any[] = [];
+		for (let i = 0; i < fieldNames.length; i++) {
+			const fieldName = fieldNames[i];
+			const fieldType = fieldTypes[i];
+			const fieldValue = value[fieldName];
+
+			// Recursively convert nested tuples
+			if (fieldType.startsWith('tuple(')) {
+				result.push(this.convertObjectToArray(fieldType, fieldValue));
+			} else {
+				result.push(fieldValue);
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Encode a value with given ABI type
+	 *
+	 * @param abiType ABI type string (e.g., "string", "uint256", "tuple(string,uint8)")
+	 * @param value Value to encode (objects are automatically converted to arrays)
+	 * @returns Encoded bytes (with 0x prefix)
+	 *
+	 * @example
+	 * // Simple value
+	 * TagAbiCodec.encode("string", "hello");
+	 *
+	 * // Array value
+	 * TagAbiCodec.encode("string[]", ["a", "b", "c"]);
+	 *
+	 * // Tuple with object input
+	 * TagAbiCodec.encode("tuple(string,uint8)", {name: "Alice", age: 30});
+	 *
+	 * // Nested tuple with object input
+	 * TagAbiCodec.encode(
+	 *   "tuple(string,tuple(uint8,bool))",
+	 *   {name: "Alice", profile: {age: 30, verified: true}}
+	 * );
+	 *
+	 * // Tuple with array input (still supported)
+	 * TagAbiCodec.encode("tuple(string,uint8)", ["Alice", 30]);
+	 */
+	static encode(abiType: string, value: any): string {
+		// Convert object to array if needed (handles nested tuples recursively)
+		const convertedValue = this.convertObjectToArray(abiType, value);
+
+		// Use ethers AbiCoder to encode
+		return this.abiCoder.encode([abiType], [convertedValue]);
+	}
+
+	/**
+	 * Decode bytes with given ABI type
+	 *
+	 * @param abiType ABI type string
+	 * @param encodedData Encoded bytes (with or without 0x prefix)
+	 * @returns Decoded value
+	 *
+	 * @example
+	 * TagAbiCodec.decode("string", encodedBytes);  // → "hello"
+	 * TagAbiCodec.decode("uint256", encodedBytes); // → 123n (BigInt)
+	 * TagAbiCodec.decode("tuple(string,uint8)", encodedBytes); // → ["Alice", 30n]
+	 */
+	static decode(abiType: string, encodedData: string): any {
+		const decoded = this.abiCoder.decode([abiType], encodedData);
+		return decoded[0];
+	}
+}

package/src/utils/tag-type-builder.ts

@@ -0,0 +1,469 @@
+/**
+ * Tag Type Builder
+ * Calculate ABI type bytes offline without contract calls
+ * Does NOT handle encoding/decoding - use TagAbiCodec for that
+ *
+ * Encoding Rules:
+ * - uint: 0x01 + size (size = bits/8)
+ * - int: 0x00 + size
+ * - bool: 0x02
+ * - string: 0x03
+ * - array: 0x04 + elementType
+ * - fixedArray: 0x05 + length (2 bytes) + elementType
+ * - tuple: 0x06 + fieldCount (2 bytes) + fieldTypes...
+ * - address: 0x07
+ * - fixedBytes: 0x08 + size
+ * - bytes: 0x09
+ */
+export class TagTypeBuilder {
+	private typeBytes: string = '';
+	private abiTypeString: string = '';
+
+	protected constructor(typeBytes: string, abiTypeString: string = '') {
+		this.typeBytes = typeBytes;
+		this.abiTypeString = abiTypeString;
+	}
+
+	/**
+	 * Get ABI type bytes (without 0x prefix)
+	 */
+	getTypeBytes(): string {
+		return this.typeBytes;
+	}
+
+	/**
+	 * Get ABI type string (e.g., "string", "uint256", "tuple(string,uint8)")
+	 */
+	getAbiTypeString(): string {
+		return this.abiTypeString;
+	}
+
+	/**
+	 * Parse type bytes to ABI type string
+	 * This is the reverse operation of building type bytes
+	 * @param typeBytes Hex string of type bytes (with or without 0x prefix)
+	 * @returns ABI type string
+	 */
+	static parseTypeBytesToAbiString(typeBytes: string): string {
+		// Remove 0x prefix if present
+		const bytes = typeBytes.startsWith('0x')
+			? typeBytes.slice(2)
+			: typeBytes;
+		if (bytes.length === 0) {
+			throw new Error('Empty type bytes');
+		}
+
+		const typeFlag = parseInt(bytes.slice(0, 2), 16);
+
+		switch (typeFlag) {
+			case 0x00: {
+				// int
+				const size = parseInt(bytes.slice(2, 4), 16);
+				return `int${size * 8}`;
+			}
+			case 0x01: {
+				// uint
+				const size = parseInt(bytes.slice(2, 4), 16);
+				return `uint${size * 8}`;
+			}
+			case 0x02: {
+				// bool
+				return 'bool';
+			}
+			case 0x03: {
+				// string
+				return 'string';
+			}
+			case 0x04: {
+				// array
+				const elementTypeBytes = '0x' + bytes.slice(2);
+				const elementType =
+					this.parseTypeBytesToAbiString(elementTypeBytes);
+				return `${elementType}[]`;
+			}
+			case 0x05: {
+				// fixedArray
+				const length = parseInt(bytes.slice(2, 6), 16);
+				const elementTypeBytes = '0x' + bytes.slice(6);
+				const elementType =
+					this.parseTypeBytesToAbiString(elementTypeBytes);
+				return `${elementType}[${length}]`;
+			}
+			case 0x06: {
+				// tuple
+				const fieldCount = parseInt(bytes.slice(2, 6), 16);
+				let offset = 6;
+				const fieldTypes: string[] = [];
+
+				for (let i = 0; i < fieldCount; i++) {
+					// Parse each field's type recursively
+					const fieldTypeBytes = '0x' + bytes.slice(offset);
+					const fieldType =
+						this.parseTypeBytesToAbiString(fieldTypeBytes);
+					fieldTypes.push(fieldType);
+
+					// Calculate the length of this field's type bytes
+					const fieldTypeBytesLength =
+						this.getTypeBytesLength(fieldTypeBytes);
+					offset += fieldTypeBytesLength;
+				}
+
+				return `tuple(${fieldTypes.join(',')})`;
+			}
+			case 0x07: {
+				// address
+				return 'address';
+			}
+			case 0x08: {
+				// fixedBytes
+				const size = parseInt(bytes.slice(2, 4), 16);
+				return `bytes${size}`;
+			}
+			case 0x09: {
+				// bytes
+				return 'bytes';
+			}
+			default:
+				throw new Error(
+					`Unknown type flag: 0x${typeFlag.toString(16)}`
+				);
+		}
+	}
+
+	/**
+	 * Calculate the byte length of a type bytes string (without 0x prefix)
+	 * @private
+	 */
+	private static getTypeBytesLength(typeBytes: string): number {
+		const bytes = typeBytes.startsWith('0x')
+			? typeBytes.slice(2)
+			: typeBytes;
+		const typeFlag = parseInt(bytes.slice(0, 2), 16);
+
+		switch (typeFlag) {
+			case 0x00: // int
+			case 0x01: // uint
+			case 0x08: // fixedBytes
+				return 4; // 1 byte flag + 1 byte size
+			case 0x02: // bool
+			case 0x03: // string
+			case 0x07: // address
+			case 0x09: // bytes
+				return 2; // 1 byte flag only
+			case 0x04: {
+				// array
+				const elementTypeBytes = '0x' + bytes.slice(2);
+				return 2 + this.getTypeBytesLength(elementTypeBytes);
+			}
+			case 0x05: {
+				// fixedArray
+				const elementTypeBytes = '0x' + bytes.slice(6);
+				return 6 + this.getTypeBytesLength(elementTypeBytes); // flag + length (2 bytes) + element type
+			}
+			case 0x06: {
+				// tuple
+				const fieldCount = parseInt(bytes.slice(2, 6), 16);
+				let length = 6; // flag + field count (2 bytes)
+				let offset = 6;
+
+				for (let i = 0; i < fieldCount; i++) {
+					const fieldTypeBytes = '0x' + bytes.slice(offset);
+					const fieldLength = this.getTypeBytesLength(fieldTypeBytes);
+					length += fieldLength;
+					offset += fieldLength;
+				}
+
+				return length;
+			}
+			default:
+				throw new Error(
+					`Unknown type flag: 0x${typeFlag.toString(16)}`
+				);
+		}
+	}
+
+	/**
+	 * Get field names (for Tuple types)
+	 * Returns format: string[][], each element is a tuple's field name array
+	 */
+	getFieldNames(): string[][] {
+		// Default returns empty array, Tuple type will override this method
+		return [];
+	}
+
+	// ========================================
+	// Basic Types
+	// ========================================
+
+	/**
+	 * uint type
+	 * @param bits Bit count: 8, 16, 24, ..., 256 (must be divisible by 8)
+	 * @example
+	 * TagTypeBuilder.uint(8)   → "0101"
+	 * TagTypeBuilder.uint(256) → "0120"
+	 */
+	static uint(bits: number = 256): TagTypeBuilder {
+		if (bits < 8 || bits > 256 || bits % 8 !== 0) {
+			throw new Error('uint bits must be 8-256 and divisible by 8');
+		}
+		const size = bits / 8;
+		const sizeHex = size.toString(16).padStart(2, '0');
+		return new TagTypeBuilder(`01${sizeHex}`, `uint${bits}`);
+	}
+
+	/**
+	 * int type
+	 * @param bits Bit count: 8, 16, 24, ..., 256 (must be divisible by 8)
+	 * @example
+	 * TagTypeBuilder.int(8)   → "0001"
+	 * TagTypeBuilder.int(256) → "0020"
+	 */
+	static int(bits: number = 256): TagTypeBuilder {
+		if (bits < 8 || bits > 256 || bits % 8 !== 0) {
+			throw new Error('int bits must be 8-256 and divisible by 8');
+		}
+		const size = bits / 8;
+		const sizeHex = size.toString(16).padStart(2, '0');
+		return new TagTypeBuilder(`00${sizeHex}`, `int${bits}`);
+	}
+
+	/**
+	 * bool type
+	 * @example
+	 * TagTypeBuilder.bool() → "02"
+	 */
+	static bool(): TagTypeBuilder {
+		return new TagTypeBuilder('02', 'bool');
+	}
+
+	/**
+	 * string type
+	 * @example
+	 * TagTypeBuilder.string() → "03"
+	 */
+	static string(): TagTypeBuilder {
+		return new TagTypeBuilder('03', 'string');
+	}
+
+	/**
+	 * address type
+	 * @example
+	 * TagTypeBuilder.address() → "07"
+	 */
+	static address(): TagTypeBuilder {
+		return new TagTypeBuilder('07', 'address');
+	}
+
+	/**
+	 * bytes type (dynamic length)
+	 * @example
+	 * TagTypeBuilder.bytes() → "09"
+	 */
+	static bytes(): TagTypeBuilder {
+		return new TagTypeBuilder('09', 'bytes');
+	}
+
+	/**
+	 * bytesN type (fixed length)
+	 * @param size Byte count: 1-32
+	 * @example
+	 * TagTypeBuilder.fixedBytes(32) → "0820"
+	 */
+	static fixedBytes(size: number): TagTypeBuilder {
+		if (size < 1 || size > 32) {
+			throw new Error('Fixed bytes size must be between 1 and 32');
+		}
+		const sizeHex = size.toString(16).padStart(2, '0');
+		return new TagTypeBuilder(`08${sizeHex}`, `bytes${size}`);
+	}
+
+	// ========================================
+	// Array Types
+	// ========================================
+
+	/**
+	 * Dynamic array
+	 * @param elementType Element type
+	 * @example
+	 * TagTypeBuilder.array(TagTypeBuilder.address()) → "0407"
+	 */
+	static array(elementType: TagTypeBuilder): TagTypeBuilder {
+		const typeBytes = `04${elementType.getTypeBytes()}`;
+		const abiTypeString = `${elementType.getAbiTypeString()}[]`;
+		const fieldNames = elementType.getFieldNames();
+
+		// If element type has field names (e.g., tuple), propagate them
+		if (fieldNames.length > 0) {
+			return new TupleTypeBuilder(typeBytes, fieldNames, abiTypeString);
+		}
+		return new TagTypeBuilder(typeBytes, abiTypeString);
+	}
+
+	/**
+	 * Fixed-length array
+	 * @param elementType Element type
+	 * @param length Array length (1-65535)
+	 * @example
+	 * TagTypeBuilder.fixedArray(TagTypeBuilder.address(), 5) → "05000507"
+	 */
+	static fixedArray(
+		elementType: TagTypeBuilder,
+		length: number
+	): TagTypeBuilder {
+		if (length < 1 || length > 65535) {
+			throw new Error('Fixed array length must be between 1 and 65535');
+		}
+		const lengthHex = length.toString(16).padStart(4, '0');
+		const typeBytes = `05${lengthHex}${elementType.getTypeBytes()}`;
+		const abiTypeString = `${elementType.getAbiTypeString()}[${length}]`;
+		const fieldNames = elementType.getFieldNames();
+
+		// If element type has field names (e.g., tuple), propagate them
+		if (fieldNames.length > 0) {
+			return new TupleTypeBuilder(typeBytes, fieldNames, abiTypeString);
+		}
+		return new TagTypeBuilder(typeBytes, abiTypeString);
+	}
+
+	// ========================================
+	// Tuple (Struct)
+	// ========================================
+
+	/**
+	 * tuple type
+	 * @param fields Field definitions, format: { fieldName: fieldType }
+	 * @example
+	 * TagTypeBuilder.tuple({
+	 *   name: TagTypeBuilder.string(),
+	 *   age: TagTypeBuilder.uint8()
+	 * }) → "060002" + "03" + "0101"
+	 *
+	 * Field names are collected in pre-order traversal (DFS pre-order) for nested tuples.
+	 * Pre-order: Visit root first, then recursively visit children left-to-right.
+	 *
+	 * Example tree structure: A{B{D{E, F}}, C}
+	 * fieldNames = [
+	 *   ["i", "j"],  // A's fields (root)
+	 *   ["i"],       // B's fields (A's 1st child)
+	 *   ["i", "j"],  // D's fields (B's child)
+	 *   ["i", "j"],  // E's fields (D's 1st child)
+	 *   ["i", "j"],  // F's fields (D's 2nd child)
+	 *   ["i"]        // C's fields (A's 2nd child)
+	 * ]
+	 */
+	static tuple(fields: Record<string, TagTypeBuilder>): TupleTypeBuilder {
+		const fieldNames: string[] = [];
+		const fieldTypes: string[] = [];
+		const fieldAbiTypes: string[] = [];
+		const allFieldNames: string[][] = [];
+
+		// First, add current tuple's field names
+		for (const name of Object.keys(fields)) {
+			fieldNames.push(name);
+		}
+		allFieldNames.push(fieldNames);
+
+		// Then, recursively collect nested tuple field names in depth-first order
+		for (const [_name, type] of Object.entries(fields)) {
+			fieldTypes.push(type.getTypeBytes());
+			fieldAbiTypes.push(type.getAbiTypeString());
+
+			// Recursively collect nested tuple field names
+			const nested = type.getFieldNames();
+			if (nested.length > 0) {
+				allFieldNames.push(...nested);
+			}
+		}
+
+		const fieldCount = fieldTypes.length;
+		const fieldCountHex = fieldCount.toString(16).padStart(4, '0');
+		const typeBytes = `06${fieldCountHex}${fieldTypes.join('')}`;
+		const abiTypeString = `tuple(${fieldAbiTypes.join(',')})`;
+
+		return new TupleTypeBuilder(
+			typeBytes,
+			allFieldNames,
+			abiTypeString,
+			fields
+		);
+	}
+
+	// ========================================
+	// Common Type Shortcuts
+	// ========================================
+
+	static uint8() {
+		return this.uint(8);
+	}
+	static uint16() {
+		return this.uint(16);
+	}
+	static uint32() {
+		return this.uint(32);
+	}
+	static uint64() {
+		return this.uint(64);
+	}
+	static uint128() {
+		return this.uint(128);
+	}
+	static uint256() {
+		return this.uint(256);
+	}
+
+	static int8() {
+		return this.int(8);
+	}
+	static int16() {
+		return this.int(16);
+	}
+	static int32() {
+		return this.int(32);
+	}
+	static int64() {
+		return this.int(64);
+	}
+	static int128() {
+		return this.int(128);
+	}
+	static int256() {
+		return this.int(256);
+	}
+
+	static bytes32() {
+		return this.fixedBytes(32);
+	}
+
+	static addressArray() {
+		return this.array(this.address());
+	}
+	static stringArray() {
+		return this.array(this.string());
+	}
+	static uint256Array() {
+		return this.array(this.uint256());
+	}
+}
+
+/**
+ * Tuple Type Builder (supports field names and object encoding)
+ */
+export class TupleTypeBuilder extends TagTypeBuilder {
+	private fieldNames: string[][];
+	private fieldTypes?: Record<string, TagTypeBuilder>;
+
+	constructor(
+		typeBytes: string,
+		fieldNames: string[][],
+		abiTypeString: string = '',
+		fieldTypes?: Record<string, TagTypeBuilder>
+	) {
+		super(typeBytes, abiTypeString);
+		this.fieldNames = fieldNames;
+		this.fieldTypes = fieldTypes;
+	}
+
+	getFieldNames(): string[][] {
+		return this.fieldNames;
+	}
+}

package/tsconfig.json

@@ -5,5 +5,5 @@
         "rootDir": "./src"
     },
     "include": ["src/**/*"],
-    "exclude": ["node_modules", "dist"]
+    "exclude": ["node_modules", "dist", "examples"]
 }