@beclab/olaresid 0.1.12 → 0.2.0

package/src/utils/crypto-utils.ts

@@ -82,7 +82,7 @@ async function loadWalletCore(): Promise<any> {
 }
 
 // multicodec code for Ed25519 keys (0xed)
-const ED25519_CODEC_ID = varint.encode(parseInt('0xed', 16));
+export const ED25519_CODEC_ID = varint.encode(parseInt('0xed', 16));
 
 // ============================================================================
 // Mnemonic and Key Derivation Functions
@@ -149,6 +149,40 @@ export async function getEthereumAddressFromMnemonic(
 	return wallet.getAddressForCoin(CoinType.ethereum);
 }
 
+/**
+ * Derive Ethereum address from private key
+ * Uses ethers.Wallet to get the address from private key
+ *
+ * @param privateKey EVM private key in hex format (with or without 0x prefix)
+ * @returns Ethereum address (0x...)
+ *
+ * @example
+ * ```typescript
+ * const address = getEthereumAddressFromPrivateKey('0x1234...');
+ * console.log(address); // "0x9858EfFD232B4033E47d90003D41EC34EcaEda94"
+ * ```
+ */
+export function getEthereumAddressFromPrivateKey(privateKey: string): string {
+	// Import ethers dynamically to match the pattern in index.ts
+	const { ethers } = require('ethers');
+
+	// Ensure privateKey has 0x prefix
+	const normalizedKey = privateKey.startsWith('0x')
+		? privateKey
+		: `0x${privateKey}`;
+
+	try {
+		const wallet = new ethers.Wallet(normalizedKey);
+		return wallet.address;
+	} catch (error) {
+		throw new Error(
+			`Invalid private key: ${
+				error instanceof Error ? error.message : String(error)
+			}`
+		);
+	}
+}
+
 /**
  * Derive EVM-compatible private key from mnemonic using Trust Wallet Core
  * Uses standard BIP44 derivation path for Ethereum (m/44'/60'/0'/0/0)
@@ -300,6 +334,7 @@ export async function getEd25519JwkFromMnemonic(mnemonic: string): Promise<{
 	idBytes.set(publicKeyBytes, ED25519_CODEC_ID.length);
 	const id = base58btc.encode(idBytes);
 	const did = `did:key:${id}`;
+	const kid = `${did}#${id}`; // Fully-qualified verification method ID
 
 	// Base64url encode the keys
 	const x = base64url.baseEncode(publicKeyBytes);
@@ -311,7 +346,7 @@ export async function getEd25519JwkFromMnemonic(mnemonic: string): Promise<{
 		crv: 'Ed25519', // Curve: Ed25519
 		alg: 'EdDSA', // Algorithm: EdDSA
 		use: 'sig', // Use: signature
-		kid: did, // DID
+		kid: kid, // Fully-qualified verification method ID (did:key:z...#z...)
 		x: x // Public key parameter
 	};
 
@@ -513,3 +548,205 @@ export function createRsaKeyPair(
 		return generateKeyPairBrowser(length);
 	}
 }
+
+// ============================================================================
+// DID Type Definitions (from @bytetrade/core)
+// ============================================================================
+
+/**
+ * Jwk base type - identifies the cryptographic algorithm family used with the key.
+ */
+interface Jwk {
+	/** The "alg" (algorithm) parameter identifies the algorithm intended for use with the key. */
+	alg?: string;
+	/** The "kid" (key ID) parameter identifies the key. */
+	kid?: string;
+	/** identifies the cryptographic algorithm family used with the key, such "EC" or "OKP". */
+	kty: string;
+	/** The "use" (public key use) parameter identifies the intended use of the public key. */
+	use?: string;
+}
+
+/**
+ * PublicJwk represents a public key in JWK format.
+ */
+export interface PublicJwk extends Jwk {
+	/** The "crv" (curve) parameter identifies the cryptographic curve used with the key. */
+	crv: string;
+	/** The x coordinate for the Elliptic Curve point, base64url encoded. */
+	x: string;
+	/** The y coordinate for the Elliptic Curve point, base64url encoded. Optional for Ed25519. */
+	y?: string;
+}
+
+/**
+ * PrivateJwk represents a private key in JWK format.
+ */
+export interface PrivateJwk extends PublicJwk {
+	/** The private key value, base64url encoded. */
+	d: string;
+}
+
+/**
+ * Linked Data Key Types - identifies the type of verification method.
+ */
+export enum LDKeyType {
+	X25519KeyAgreementKey2020 = 'X25519KeyAgreementKey2020',
+	Ed25519VerificationKey2020 = 'Ed25519VerificationKey2020',
+	X25519KeyAgreementKey2019 = 'X25519KeyAgreementKey2019',
+	Ed25519VerificationKey2018 = 'Ed25519VerificationKey2018',
+	EcdsaSecp256k1VerificationKey2019 = 'EcdsaSecp256k1VerificationKey2019'
+}
+
+/**
+ * VerificationMethod represents a verification method in a DID document.
+ */
+export interface VerificationMethod {
+	id: string;
+	type: LDKeyType | string;
+	controller: string;
+	publicKeyBase58?: string;
+	publicKeyJwk?: PublicJwk;
+	publicKeyMultibase?: string;
+	blockchainAccountId?: string;
+}
+
+/**
+ * DIDDocument represents a W3C DID Document.
+ */
+export interface DIDDocument {
+	'@context'?: any;
+	id?: string;
+	controller?: string;
+	alsoKnownAs?: string;
+	verificationMethod?: VerificationMethod[];
+	authentication?: (string | VerificationMethod)[];
+	assertionMethod?: (string | VerificationMethod)[];
+	keyAgreement?: (string | VerificationMethod)[];
+	capabilityInvocation?: (string | VerificationMethod)[];
+	capabilityDelegation?: (string | VerificationMethod)[];
+	services?: Service[];
+}
+
+/**
+ * Service endpoint in a DID document.
+ */
+export interface Service {
+	id: string;
+	type: string;
+	serviceEndpoint: any;
+	routingKeys?: string[];
+	accept?: string[];
+}
+
+// ============================================================================
+// DID / JWK Utilities
+// ============================================================================
+
+/**
+ * Build a fully-qualified verification method ID from a DID.
+ * e.g. "did:key:z6Mk..." → "did:key:z6Mk...#z6Mk..."
+ */
+export function getFullyQualifiedVerificationMethodID(did: string): string {
+	const base = did.split('#')[0];
+	const [, , id] = base.split(':');
+	return `${base}#${id}`;
+}
+
+/**
+ * Construct a PublicJwk from a DID and an already-decoded base64url `x` value.
+ */
+export function getPublicJWKFromX(did: string, x: string): PublicJwk {
+	return {
+		alg: 'EdDSA',
+		crv: 'Ed25519',
+		kid: did,
+		kty: 'OKP',
+		use: 'sig',
+		x
+	};
+}
+
+/**
+ * Derive a PublicJwk directly from a did:key string.
+ */
+export function getPublicJWKFromDID(did: string): PublicJwk {
+	const base = did.split('#')[0];
+	const [scheme, method, id] = base.split(':');
+	if (scheme !== 'did')
+		throw new Error('Malformed DID: scheme must be "did"');
+	if (method !== 'key')
+		throw new Error('Unsupported DID method: must be "key"');
+
+	const idBytes = base58btc.decode(id);
+	const x = base64url.baseEncode(idBytes.slice(ED25519_CODEC_ID.length));
+	return getPublicJWKFromX(base, x);
+}
+
+/**
+ * Construct a PrivateJwk from a DID and a base64url-encoded private key `d`.
+ */
+export function getPrivateJWKFromD(did: string, d: string): PrivateJwk {
+	return { ...getPublicJWKFromDID(did), d };
+}
+
+/**
+ * Encode a raw Ed25519 public key (Uint8Array) to a multicodec base58btc id string.
+ */
+export function getIDFromEd25519Pubkey(publicKey: Uint8Array): string {
+	const idBytes = new Uint8Array(publicKey.length + ED25519_CODEC_ID.length);
+	idBytes.set(ED25519_CODEC_ID, 0);
+	idBytes.set(publicKey, ED25519_CODEC_ID.length);
+	return base58btc.encode(idBytes);
+}
+
+/**
+ * Construct a PrivateJwk from raw Ed25519 public/private key bytes.
+ */
+export function getPrivateJWKFromEd25519(
+	publicKey: Uint8Array,
+	privateKey: Uint8Array
+): PrivateJwk {
+	const id = getIDFromEd25519Pubkey(publicKey);
+	const keyId = `did:key:${id}#${id}`;
+	return {
+		alg: 'EdDSA',
+		crv: 'Ed25519',
+		kid: keyId,
+		kty: 'OKP',
+		use: 'sig',
+		x: base64url.baseEncode(publicKey),
+		d: base64url.baseEncode(privateKey)
+	};
+}
+
+/**
+ * Resolve a did:key DID into a W3C DIDDocument.
+ */
+export function resolveDID(did: string): DIDDocument {
+	const publicJwk = getPublicJWKFromDID(did);
+	const base = did.split('#')[0];
+	const [, , id] = base.split(':');
+	const methodId = `#${id}`;
+
+	return {
+		'@context': [
+			'https://www.w3.org/ns/did/v1',
+			'https://w3id.org/security/suites/ed25519-2020/v1',
+			'https://w3id.org/security/suites/x25519-2020/v1'
+		],
+		id: base,
+		verificationMethod: [
+			{
+				id: methodId,
+				type: LDKeyType.Ed25519VerificationKey2020,
+				controller: base,
+				publicKeyJwk: publicJwk
+			}
+		],
+		authentication: [methodId],
+		assertionMethod: [methodId],
+		capabilityDelegation: [methodId],
+		capabilityInvocation: [methodId]
+	};
+}

package/src/utils/error-parser.ts

@@ -108,7 +108,8 @@ export function parseContractError(error: any): ParsedContractError {
 			const errorSelector = error.data.slice(0, 10);
 			errorName = ERROR_SELECTORS[errorSelector];
 		} catch (e) {
-			// Ignore parsing errors
+			console.error('[error-parser] failed to parse error selector', e);
+			throw e;
 		}
 	}
 

package/src/utils/event-parser.ts

@@ -0,0 +1,353 @@
+import { ethers } from 'ethers';
+import DID_ABI from '../abi/TerminusDIDABI';
+
+// ============================================================
+// Raw Log Type (from eth_getLogs RPC response)
+// ============================================================
+
+export interface EthLog {
+	address: string;
+	topics: string[];
+	data: string;
+	blockNumber: string; // hex string
+	transactionHash: string;
+	transactionIndex: string; // hex string
+	blockHash: string;
+	logIndex: string; // hex string
+	removed: boolean;
+}
+
+// ============================================================
+// Event Args Types
+// ============================================================
+
+/** Transfer (ERC721) — from=0x0 means mint */
+export interface TransferArgs {
+	from: string;
+	to: string;
+	tokenId: bigint;
+}
+
+/** Approval (ERC721) */
+export interface ApprovalArgs {
+	owner: string;
+	approved: string;
+	tokenId: bigint;
+}
+
+/** ApprovalForAll (ERC721) */
+export interface ApprovalForAllArgs {
+	owner: string;
+	operator: string;
+	approved: boolean;
+}
+
+/** Initialized — emitted on proxy initialization */
+export interface InitializedArgs {
+	version: bigint;
+}
+
+/** NewTagType — emitted when a tag type is defined via defineTag() */
+export interface NewTagTypeArgs {
+	domain: string;
+	name: string;
+	abiType: string; // bytes, hex string
+	fieldNamesHash: string[]; // bytes32[]
+}
+
+/** OffchainStringArray — emitted to log string[] values off-chain */
+export interface OffchainStringArrayArgs {
+	hash: string; // bytes32, indexed
+	value: string[];
+}
+
+/** OwnershipTransferStarted */
+export interface OwnershipTransferStartedArgs {
+	previousOwner: string;
+	newOwner: string;
+}
+
+/** OwnershipTransferred */
+export interface OwnershipTransferredArgs {
+	previousOwner: string;
+	newOwner: string;
+}
+
+/** TagAdded — emitted when a tag value is set on a domain */
+export interface TagAddedArgs {
+	from: string; // domain that owns the tag definition
+	to: string; // domain being tagged
+	name: string;
+	value: string; // bytes, hex string
+}
+
+/** TagElemPopped — array element removed from a tag */
+export interface TagElemPoppedArgs {
+	from: string;
+	to: string;
+	name: string;
+	elemPath: bigint[]; // uint256[]
+}
+
+/** TagElemPushed — array element appended to a tag */
+export interface TagElemPushedArgs {
+	from: string;
+	to: string;
+	name: string;
+	elemPath: bigint[]; // uint256[]
+	value: string; // bytes, hex string
+}
+
+/** TagElemUpdated — array element updated in a tag */
+export interface TagElemUpdatedArgs {
+	from: string;
+	to: string;
+	name: string;
+	elemPath: bigint[]; // uint256[]
+	value: string; // bytes, hex string
+}
+
+/** TagRemoved — tag value removed from a domain */
+export interface TagRemovedArgs {
+	from: string;
+	to: string;
+	name: string;
+}
+
+/** TransferByParentOwner — subdomain transferred by parent domain owner */
+export interface TransferByParentOwnerArgs {
+	tokenId: bigint;
+}
+
+/** TransferBySuperAdmin — domain transferred by super admin */
+export interface TransferBySuperAdminArgs {
+	tokenId: bigint;
+}
+
+/** Upgraded — UUPS proxy upgraded to new implementation */
+export interface UpgradedArgs {
+	implementation: string;
+}
+
+// ============================================================
+// Event Name Union & Args Map
+// ============================================================
+
+export type TerminusDIDEventName =
+	| 'Transfer'
+	| 'Approval'
+	| 'ApprovalForAll'
+	| 'Initialized'
+	| 'NewTagType'
+	| 'OffchainStringArray'
+	| 'OwnershipTransferStarted'
+	| 'OwnershipTransferred'
+	| 'TagAdded'
+	| 'TagElemPopped'
+	| 'TagElemPushed'
+	| 'TagElemUpdated'
+	| 'TagRemoved'
+	| 'TransferByParentOwner'
+	| 'TransferBySuperAdmin'
+	| 'Upgraded';
+
+export interface TerminusDIDEventArgsMap {
+	Transfer: TransferArgs;
+	Approval: ApprovalArgs;
+	ApprovalForAll: ApprovalForAllArgs;
+	Initialized: InitializedArgs;
+	NewTagType: NewTagTypeArgs;
+	OffchainStringArray: OffchainStringArrayArgs;
+	OwnershipTransferStarted: OwnershipTransferStartedArgs;
+	OwnershipTransferred: OwnershipTransferredArgs;
+	TagAdded: TagAddedArgs;
+	TagElemPopped: TagElemPoppedArgs;
+	TagElemPushed: TagElemPushedArgs;
+	TagElemUpdated: TagElemUpdatedArgs;
+	TagRemoved: TagRemovedArgs;
+	TransferByParentOwner: TransferByParentOwnerArgs;
+	TransferBySuperAdmin: TransferBySuperAdminArgs;
+	Upgraded: UpgradedArgs;
+}
+
+// ============================================================
+// Parsed Event Types
+// ============================================================
+
+export interface ParsedEvent<T extends TerminusDIDEventName> {
+	eventName: T;
+	blockNumber: number;
+	transactionHash: string;
+	logIndex: number;
+	tokenId: bigint | undefined;
+	args: TerminusDIDEventArgsMap[T];
+	raw: EthLog;
+}
+
+export type AnyParsedEvent = {
+	[K in TerminusDIDEventName]: ParsedEvent<K>;
+}[TerminusDIDEventName];
+
+// ============================================================
+// Type Guards
+// ============================================================
+
+export function isTransferEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'Transfer'> {
+	return event.eventName === 'Transfer';
+}
+
+export function isMintEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'Transfer'> {
+	return (
+		event.eventName === 'Transfer' &&
+		event.args.from === '0x0000000000000000000000000000000000000000'
+	);
+}
+
+export function isTagAddedEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'TagAdded'> {
+	return event.eventName === 'TagAdded';
+}
+
+export function isTagRemovedEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'TagRemoved'> {
+	return event.eventName === 'TagRemoved';
+}
+
+export function isTagElemUpdatedEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'TagElemUpdated'> {
+	return event.eventName === 'TagElemUpdated';
+}
+
+export function isTagElemPushedEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'TagElemPushed'> {
+	return event.eventName === 'TagElemPushed';
+}
+
+export function isTagElemPoppedEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'TagElemPopped'> {
+	return event.eventName === 'TagElemPopped';
+}
+
+export function isNewTagTypeEvent(
+	event: AnyParsedEvent
+): event is ParsedEvent<'NewTagType'> {
+	return event.eventName === 'NewTagType';
+}
+
+// ============================================================
+// Parser
+// ============================================================
+
+const _iface = new ethers.Interface(DID_ABI.abi);
+
+/**
+ * Derive tokenId from a domain name, matching the on-chain formula:
+ *   uint256(keccak256(bytes(domain)))
+ */
+function domainToTokenId(domain: string): bigint {
+	return BigInt(ethers.keccak256(ethers.toUtf8Bytes(domain)));
+}
+
+/**
+ * Extract tokenId from event args.
+ *
+ * ✅ directly in args:  Transfer, TransferByParentOwner, TransferBySuperAdmin
+ * ✅ derived locally:   NewTagType (args.domain), Tag* events (args.to)
+ * ❌ not applicable:    Approval, ApprovalForAll, Initialized, Upgraded,
+ *                       OwnershipTransferred*, OffchainStringArray
+ */
+function extractTokenId(
+	eventName: TerminusDIDEventName,
+	args: Record<string, unknown>
+): bigint | undefined {
+	switch (eventName) {
+		case 'Transfer':
+		case 'TransferByParentOwner':
+		case 'TransferBySuperAdmin':
+			return args['tokenId'] as bigint;
+		case 'NewTagType':
+			return domainToTokenId(args['domain'] as string);
+		case 'TagAdded':
+		case 'TagRemoved':
+		case 'TagElemUpdated':
+		case 'TagElemPushed':
+		case 'TagElemPopped':
+			return domainToTokenId(args['to'] as string);
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Parse raw eth_getLogs entries using the TerminusDID contract ABI.
+ *
+ * Logs that don't match any known event (e.g. from a different contract)
+ * are silently skipped.
+ *
+ * @example
+ * ```typescript
+ * const logs = await provider.getLogs({ address: CONTRACT_ADDRESS, fromBlock, toBlock });
+ * const events = parseEvents(logs);
+ * for (const event of events) {
+ *   if (isTransferEvent(event)) {
+ *     console.log('Transfer:', event.args.from, '->', event.args.to, event.args.tokenId);
+ *   }
+ * }
+ * ```
+ */
+export function parseEvents(logs: EthLog[]): AnyParsedEvent[] {
+	const result: AnyParsedEvent[] = [];
+
+	for (const log of logs) {
+		try {
+			const parsed = _iface.parseLog({
+				topics: log.topics,
+				data: log.data
+			});
+			if (!parsed) {
+				console.warn(
+					'[event-parser] parseLog returned null, matching event cannot be found',
+					{
+						tx: log.transactionHash,
+						logIndex: log.logIndex
+					}
+				);
+				continue;
+			}
+
+			const args: Record<string, unknown> = {};
+			parsed.fragment.inputs.forEach((input, idx) => {
+				args[input.name] = parsed.args[idx];
+			});
+
+			const eventName = parsed.name as TerminusDIDEventName;
+			result.push({
+				eventName,
+				blockNumber: parseInt(log.blockNumber, 16),
+				transactionHash: log.transactionHash,
+				logIndex: parseInt(log.logIndex, 16),
+				tokenId: extractTokenId(eventName, args),
+				args: args as unknown as TerminusDIDEventArgsMap[TerminusDIDEventName],
+				raw: log
+			} as AnyParsedEvent);
+		} catch (err) {
+			console.error('[event-parser] failed to parse log', {
+				tx: log.transactionHash,
+				logIndex: log.logIndex,
+				err
+			});
+			throw err;
+		}
+	}
+
+	return result;
+}