@d9-network/ink 1.0.2 → 1.1.0

package/dist/index.cjs

@@ -630,12 +630,46 @@ var ContractEventParser = class {
 		return this.filterEvents(chainEvents).filter((e) => e.type === label);
 	}
 	/**
+	* Parse chain event records with proper typing
+	*
+	* Unlike parseEvent/filterEvents which accept `unknown[]`, this method
+	* accepts typed `ChainEventRecord[]` which eliminates the need for
+	* `as any` casts in user code.
+	*
+	* @param events - Array of typed chain event records
+	* @param options - Optional filter criteria
+	* @returns Array of typed contract events
+	*
+	* @example
+	* ```ts
+	* // No more `as any` needed!
+	* const events: ChainEventRecord[] = await api.query.System.Events.getValue();
+	* const contractEvents = parser.parseChainEvents(events);
+	*
+	* for (const event of contractEvents) {
+	*   if (event.type === "Transfer") {
+	*     // Fully typed!
+	*     console.log(event.value.from, event.value.to, event.value.value);
+	*   }
+	* }
+	* ```
+	*/
+	parseChainEvents(events, options) {
+		return this.filterEvents(events, options);
+	}
+	/**
 	* Get the contract address as SS58 string
 	*/
 	getContractAddress() {
 		return this.contractAddress;
 	}
 	/**
+	* Get the contract address as bytes
+	*/
+	getContractAddressBytes() {
+		return this.contractAddressBytes;
+	}
+	/**
 	* Extract ContractEmitted event from chain event structure
 	* Based on polkadot-api event format
 	*/
@@ -1348,6 +1382,101 @@ function createD9InkSdk(client, options = {}) {
 	};
 }
 
+//#endregion
+//#region src/event-types.ts
+/**
+* Type guard for Contracts.ContractEmitted events
+*
+* @example
+* ```ts
+* for (const event of events) {
+*   if (isContractEmittedEvent(event)) {
+*     // event.event.value.value is ContractEmittedValue
+*     const { contract, data } = event.event.value.value;
+*   }
+* }
+* ```
+*/
+function isContractEmittedEvent(event) {
+	return event.event?.type === "Contracts" && event.event?.value?.type === "ContractEmitted";
+}
+/**
+* Type guard for Contracts.Called events
+*
+* @example
+* ```ts
+* for (const event of events) {
+*   if (isContractCalledEvent(event)) {
+*     // event.event.value.value is ContractCalledValue
+*     const { caller, contract } = event.event.value.value;
+*   }
+* }
+* ```
+*/
+function isContractCalledEvent(event) {
+	return event.event?.type === "Contracts" && event.event?.value?.type === "Called";
+}
+/**
+* Type guard for Balances.Transfer events
+*
+* @example
+* ```ts
+* for (const event of events) {
+*   if (isBalancesTransferEvent(event)) {
+*     const { from, to, amount } = event.event.value.value;
+*   }
+* }
+* ```
+*/
+function isBalancesTransferEvent(event) {
+	return event.event?.type === "Balances" && event.event?.value?.type === "Transfer";
+}
+/**
+* Check if event is in ApplyExtrinsic phase
+*
+* @example
+* ```ts
+* for (const event of events) {
+*   if (isApplyExtrinsicPhase(event)) {
+*     const extrinsicIndex = event.phase.value;
+*   }
+* }
+* ```
+*/
+function isApplyExtrinsicPhase(event) {
+	return event.phase?.type === "ApplyExtrinsic" && typeof event.phase.value === "number";
+}
+/**
+* Extract contract emitted data with proper typing
+*
+* Handles both Uint8Array and Binary object formats.
+*
+* @param event - Chain event record
+* @returns Extracted data or null if not a ContractEmitted event
+*/
+function extractContractEmittedData(event) {
+	if (!isContractEmittedEvent(event)) return null;
+	const { contract: contractRaw, data: dataRaw } = event.event.value.value;
+	let contract;
+	if (contractRaw instanceof Uint8Array) contract = contractRaw;
+	else if (typeof contractRaw === "string") contract = new Uint8Array(0);
+	else return null;
+	let data;
+	if (dataRaw instanceof Uint8Array) data = dataRaw;
+	else if (dataRaw && typeof dataRaw === "object" && "asBytes" in dataRaw && typeof dataRaw.asBytes === "function") data = dataRaw.asBytes();
+	else return null;
+	const topics = [];
+	if (event.topics && Array.isArray(event.topics)) {
+		for (const topic of event.topics) if (topic instanceof Uint8Array) topics.push(topic);
+		else if (topic && typeof topic === "object" && "asBytes" in topic && typeof topic.asBytes === "function") topics.push(topic.asBytes());
+	}
+	return {
+		contract,
+		data,
+		topics
+	};
+}
+
 //#endregion
 //#region src/codec-builder-internal.ts
 /**
@@ -1674,6 +1803,97 @@ var ContractCallParser = class {
 		for (let i = 0; i < selector.length; i++) if (selector[i] !== info.selector[i]) return false;
 		return true;
 	}
+	/**
+	* Get selector for a message label
+	*
+	* @param label - Message label (e.g., "PSP22::transfer")
+	* @returns Selector as Uint8Array or null if not found
+	*
+	* @example
+	* ```ts
+	* const selector = parser.getSelector("PSP22::transfer");
+	* // selector is Uint8Array([0xdb, 0x20, 0xf9, 0xf5])
+	* ```
+	*/
+	getSelector(label) {
+		return this.messageDecoders.get(label)?.selector ?? null;
+	}
+	/**
+	* Get selector as hex string for a message label
+	*
+	* @param label - Message label (e.g., "PSP22::transfer")
+	* @returns Selector hex string (without 0x) or null if not found
+	*
+	* @example
+	* ```ts
+	* const selectorHex = parser.getSelectorHex("PSP22::transfer");
+	* // selectorHex is "db20f9f5"
+	* ```
+	*/
+	getSelectorHex(label) {
+		const selector = this.getSelector(label);
+		if (!selector) return null;
+		return Array.from(selector).map((b) => b.toString(16).padStart(2, "0")).join("");
+	}
+	/**
+	* Get the label for a selector
+	*
+	* @param selector - Selector as Uint8Array or hex string (with or without 0x)
+	* @returns Message label or null if not found
+	*
+	* @example
+	* ```ts
+	* const label = parser.getLabel("db20f9f5");
+	* // label is "PSP22::transfer"
+	*
+	* // Also works with Uint8Array
+	* const label2 = parser.getLabel(callData.slice(0, 4));
+	* ```
+	*/
+	getLabel(selector) {
+		const selectorHex = this.normalizeSelector(selector);
+		return this.selectorToLabel.get(selectorHex) ?? null;
+	}
+	/**
+	* Get all selector-to-label mappings
+	*
+	* @returns Map of selector hex (without 0x) -> label
+	*
+	* @example
+	* ```ts
+	* const map = parser.getSelectorMap();
+	* for (const [selectorHex, label] of map) {
+	*   console.log(`${selectorHex} -> ${label}`);
+	* }
+	* ```
+	*/
+	getSelectorMap() {
+		return new Map(this.selectorToLabel);
+	}
+	/**
+	* Check if a selector exists in this contract
+	*
+	* @param selector - Selector to check (Uint8Array or hex string)
+	* @returns True if selector is valid for this contract
+	*
+	* @example
+	* ```ts
+	* if (parser.hasSelector("db20f9f5")) {
+	*   // This selector is valid for this contract
+	* }
+	* ```
+	*/
+	hasSelector(selector) {
+		const selectorHex = this.normalizeSelector(selector);
+		return this.selectorToLabel.has(selectorHex);
+	}
+	/**
+	* Normalize selector to hex string (without 0x prefix)
+	*/
+	normalizeSelector(selector) {
+		if (selector instanceof Uint8Array) return Array.from(selector).map((b) => b.toString(16).padStart(2, "0")).join("");
+		return selector.startsWith("0x") ? selector.slice(2).toLowerCase() : selector.toLowerCase();
+	}
 };
 /**
 * Type guard for narrowing call types
@@ -1703,6 +1923,383 @@ function isCallType(call, label) {
 	return call.type === label;
 }
 
+//#endregion
+//#region src/selectors.ts
+/**
+* PSP22 standard selectors for quick reference
+*
+* These are derived from the PSP22 standard and are consistent across implementations.
+* Use these when you need to quickly check if call data matches a specific PSP22 method.
+*
+* @example
+* ```ts
+* import { PSP22_SELECTORS, extractSelectorHex } from "@d9-network/ink";
+*
+* const selectorHex = extractSelectorHex(callData);
+* if (selectorHex === PSP22_SELECTORS.transfer) {
+*   // This is a PSP22::transfer call
+* }
+* ```
+*/
+const PSP22_SELECTORS = {
+	totalSupply: "162df8c2",
+	balanceOf: "6568382f",
+	allowance: "4d47d921",
+	transfer: "db20f9f5",
+	transferFrom: "54b3c76e",
+	approve: "b20f1bbd",
+	increaseAllowance: "96d6b57a",
+	decreaseAllowance: "fecb57d5"
+};
+/**
+* Build a selector lookup map from contract metadata
+*
+* @param metadata - Contract metadata
+* @returns Map of selector hex (without 0x) -> SelectorInfo
+*
+* @example
+* ```ts
+* import { contracts } from "@d9-network/spec";
+* import { buildSelectorMap } from "@d9-network/ink";
+*
+* const selectors = buildSelectorMap(contracts.usdt.metadata);
+* const info = selectors.get("db20f9f5");
+* if (info) {
+*   console.log(info.label); // "PSP22::transfer"
+* }
+* ```
+*/
+function buildSelectorMap(metadata) {
+	const map$1 = /* @__PURE__ */ new Map();
+	const messages = metadata.spec.messages;
+	for (const message of messages) {
+		const selectorHex = message.selector.startsWith("0x") ? message.selector.slice(2).toLowerCase() : message.selector.toLowerCase();
+		const selector = hexToBytes(selectorHex);
+		map$1.set(selectorHex, {
+			label: message.label,
+			selector,
+			selectorHex,
+			mutates: message.mutates,
+			payable: message.payable
+		});
+	}
+	return map$1;
+}
+/**
+* Build a reverse lookup map (label -> selector info)
+*
+* @param metadata - Contract metadata
+* @returns Map of label -> SelectorInfo
+*
+* @example
+* ```ts
+* const labelMap = buildLabelMap(contracts.usdt.metadata);
+* const info = labelMap.get("PSP22::transfer");
+* console.log(info?.selectorHex); // "db20f9f5"
+* ```
+*/
+function buildLabelMap(metadata) {
+	const map$1 = /* @__PURE__ */ new Map();
+	const selectorMap = buildSelectorMap(metadata);
+	for (const info of selectorMap.values()) map$1.set(info.label, info);
+	return map$1;
+}
+/**
+* Get selector for a message label
+*
+* @param metadata - Contract metadata
+* @param label - Message label (e.g., "PSP22::transfer")
+* @returns Selector info or null if not found
+*
+* @example
+* ```ts
+* const info = getSelectorForLabel(contracts.usdt.metadata, "PSP22::transfer");
+* console.log(info?.selectorHex); // "db20f9f5"
+* ```
+*/
+function getSelectorForLabel(metadata, label) {
+	return buildLabelMap(metadata).get(label) ?? null;
+}
+/**
+* Get message label for a selector
+*
+* @param metadata - Contract metadata
+* @param selector - Selector as Uint8Array or hex string (with or without 0x)
+* @returns Selector info or null if not found
+*
+* @example
+* ```ts
+* const info = getLabelForSelector(contracts.usdt.metadata, "db20f9f5");
+* console.log(info?.label); // "PSP22::transfer"
+*
+* // Also works with Uint8Array
+* const info2 = getLabelForSelector(contracts.usdt.metadata, callData.slice(0, 4));
+* ```
+*/
+function getLabelForSelector(metadata, selector) {
+	const selectorHex = normalizeSelector(selector);
+	return buildSelectorMap(metadata).get(selectorHex) ?? null;
+}
+/**
+* Check if call data matches a specific message
+*
+* @param metadata - Contract metadata
+* @param callData - Call data bytes or hex string
+* @param label - Message label to check
+* @returns True if the call data selector matches the label
+*
+* @example
+* ```ts
+* if (isMessageCall(contracts.usdt.metadata, callData, "PSP22::transfer")) {
+*   // This is a transfer call
+* }
+* ```
+*/
+function isMessageCall(metadata, callData, label) {
+	const bytes = typeof callData === "string" ? hexToBytes(callData) : callData;
+	if (bytes.length < 4) return false;
+	const callSelectorHex = bytesToHex(bytes.slice(0, 4));
+	const info = getSelectorForLabel(metadata, label);
+	return info !== null && info.selectorHex === callSelectorHex;
+}
+/**
+* Check if call data matches a PSP22 method
+*
+* @param callData - Call data bytes or hex string
+* @param method - PSP22 method name (e.g., "transfer", "transferFrom")
+* @returns True if the call data selector matches the PSP22 method
+*
+* @example
+* ```ts
+* if (isPSP22Call(callData, "transfer")) {
+*   // This is a PSP22::transfer call
+* }
+* ```
+*/
+function isPSP22Call(callData, method) {
+	const bytes = typeof callData === "string" ? hexToBytes(callData) : callData;
+	if (bytes.length < 4) return false;
+	return bytesToHex(bytes.slice(0, 4)) === PSP22_SELECTORS[method];
+}
+/**
+* Get all selectors from contract metadata
+*
+* @param metadata - Contract metadata
+* @returns Array of SelectorInfo for all messages
+*/
+function getAllSelectors(metadata) {
+	const selectorMap = buildSelectorMap(metadata);
+	return Array.from(selectorMap.values());
+}
+function normalizeSelector(selector) {
+	if (selector instanceof Uint8Array) return bytesToHex(selector);
+	return selector.startsWith("0x") ? selector.slice(2).toLowerCase() : selector.toLowerCase();
+}
+function hexToBytes(hex) {
+	const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+	const bytes = new Uint8Array(clean.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+function bytesToHex(bytes) {
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+	return hex;
+}
+
+//#endregion
+//#region src/extrinsic-parser.ts
+/**
+* Parser for extracting contract calls from extrinsics
+*
+* This class provides a high-level API for indexers to parse contract
+* interactions from blockchain extrinsics without manual hex manipulation.
+*
+* @typeParam S - The storage descriptor type
+* @typeParam M - The InkCallableDescriptor type (message definitions)
+* @typeParam C - The constructors descriptor type
+* @typeParam E - The events type
+*
+* @example
+* ```ts
+* import { ExtrinsicParser } from "@d9-network/ink";
+* import { contracts } from "@d9-network/spec";
+*
+* // Create parser for USDT contract
+* const parser = new ExtrinsicParser(contracts.usdt, {
+*   contractAddresses: [USDT_ADDRESS],
+* });
+*
+* // Parse extrinsics from a block
+* for (const extrinsic of block.extrinsics) {
+*   const parsed = parser.parseExtrinsic(extrinsic);
+*   if (parsed?.call.type === "PSP22::transfer") {
+*     console.log(`Transfer: ${parsed.call.args.value} to ${parsed.call.args.to}`);
+*   }
+* }
+* ```
+*/
+var ExtrinsicParser = class {
+	callParser;
+	options;
+	constructor(descriptor, options = {}) {
+		this.callParser = new ContractCallParser(descriptor);
+		this.options = options;
+	}
+	/**
+	* Parse a single extrinsic for contract calls
+	*
+	* @param extrinsic - Raw extrinsic data
+	* @returns Parsed contract extrinsic or null if not a valid contract call
+	*/
+	parseExtrinsic(extrinsic) {
+		if (!this.isContractCall(extrinsic)) return null;
+		const extracted = this.extractCallData(extrinsic);
+		if (!extracted) return null;
+		const { data, contractAddress, value } = extracted;
+		if (this.options.contractAddresses && this.options.contractAddresses.length > 0 && !this.options.contractAddresses.includes(contractAddress)) return null;
+		const raw = {
+			data,
+			contractAddress,
+			txHash: extrinsic.hash,
+			blockNumber: extrinsic.blockNumber,
+			blockHash: extrinsic.blockHash
+		};
+		const call = this.callParser.parseCall(raw);
+		if (!call) return null;
+		if (this.options.messageLabels && this.options.messageLabels.length > 0 && !this.options.messageLabels.includes(call.type)) return null;
+		return {
+			call,
+			extrinsic: {
+				hash: extrinsic.hash ?? "",
+				blockNumber: extrinsic.blockNumber ?? 0,
+				blockHash: extrinsic.blockHash ?? "",
+				index: extrinsic.index ?? 0,
+				signer: String(extrinsic.signer ?? "")
+			},
+			contractAddress,
+			value
+		};
+	}
+	/**
+	* Parse multiple extrinsics and filter contract calls
+	*
+	* @param extrinsics - Array of raw extrinsics
+	* @returns Array of parsed contract extrinsics
+	*/
+	parseExtrinsics(extrinsics) {
+		const results = [];
+		for (const extrinsic of extrinsics) {
+			const parsed = this.parseExtrinsic(extrinsic);
+			if (parsed) results.push(parsed);
+		}
+		return results;
+	}
+	/**
+	* Filter extrinsics by message type with type narrowing
+	*
+	* @param extrinsics - Array of raw extrinsics
+	* @param label - Message label to filter by
+	* @returns Filtered and typed extrinsics
+	*
+	* @example
+	* ```ts
+	* const transfers = parser.filterByMessageType(extrinsics, "PSP22::transfer");
+	* for (const tx of transfers) {
+	*   // tx.call.args is fully typed
+	*   console.log(tx.call.args.to, tx.call.args.value);
+	* }
+	* ```
+	*/
+	filterByMessageType(extrinsics, label) {
+		return this.parseExtrinsics(extrinsics).filter((tx) => tx.call.type === label);
+	}
+	/**
+	* Check if an extrinsic is a contract call
+	*
+	* @param extrinsic - Raw extrinsic
+	* @returns True if this is a Contracts.call extrinsic
+	*/
+	isContractCall(extrinsic) {
+		const call = extrinsic.call;
+		if (!call) return false;
+		if (call.type === "Contracts") {
+			const innerCall = call.value;
+			return innerCall?.type === "call" || innerCall?.type === "call_old_weight" || innerCall?.type === "instantiate_with_code" || innerCall?.type === "instantiate";
+		}
+		return false;
+	}
+	/**
+	* Extract call data from an extrinsic structure
+	*
+	* Handles various extrinsic formats (polkadot-api, subsquid, etc.)
+	*
+	* @param extrinsic - Raw extrinsic
+	* @returns Extracted call data or null
+	*/
+	extractCallData(extrinsic) {
+		const call = extrinsic.call;
+		if (!call?.value?.value) return null;
+		const contractsCall = call.value.value;
+		const contractAddress = this.extractContractAddress(contractsCall.dest);
+		if (!contractAddress) return null;
+		const data = this.extractBytes(contractsCall.data);
+		if (!data || data.length < 4) return null;
+		return {
+			data,
+			contractAddress,
+			value: this.extractBigInt(contractsCall.value)
+		};
+	}
+	/**
+	* Get access to the underlying call parser
+	*/
+	getCallParser() {
+		return this.callParser;
+	}
+	extractContractAddress(dest) {
+		if (!dest) return null;
+		if (typeof dest === "string") return dest;
+		if (typeof dest === "object" && "type" in dest && "value" in dest) return dest.value;
+		if (typeof dest === "object" && "Id" in dest) return dest.Id;
+		return null;
+	}
+	extractBytes(data) {
+		if (!data) return null;
+		if (data instanceof Uint8Array) return data;
+		if (typeof data === "object" && "asBytes" in data && typeof data.asBytes === "function") return data.asBytes();
+		return null;
+	}
+	extractBigInt(value) {
+		if (value === void 0 || value === null) return 0n;
+		if (typeof value === "bigint") return value;
+		if (typeof value === "number") return BigInt(value);
+		if (typeof value === "string") try {
+			return BigInt(value);
+		} catch {
+			return 0n;
+		}
+		return 0n;
+	}
+};
+/**
+* Create an extrinsic parser from a contract descriptor
+*
+* @param descriptor - Contract descriptor
+* @param options - Parser options
+* @returns ExtrinsicParser instance
+*
+* @example
+* ```ts
+* const parser = createExtrinsicParser(contracts.usdt, {
+*   contractAddresses: [USDT_ADDRESS],
+* });
+* ```
+*/
+function createExtrinsicParser(descriptor, options) {
+	return new ExtrinsicParser(descriptor, options);
+}
+
 //#endregion
 //#region src/utils/fees.ts
 const WEIGHT_REF_TIME_PER_SECOND = 1000000000000n;
@@ -1857,6 +2454,7 @@ Object.defineProperty(exports, 'EncodeError', {
     return _d9_network_spec.EncodeError;
   }
 });
+exports.ExtrinsicParser = ExtrinsicParser;
 exports.InkCodecs = InkCodecs;
 Object.defineProperty(exports, 'LangError', {
   enumerable: true,
@@ -1876,6 +2474,7 @@ Object.defineProperty(exports, 'NetworkError', {
     return _d9_network_spec.NetworkError;
   }
 });
+exports.PSP22_SELECTORS = PSP22_SELECTORS;
 Object.defineProperty(exports, 'SignerError', {
   enumerable: true,
   get: function () {
@@ -1898,13 +2497,16 @@ exports.applyGasMargin = applyGasMargin;
 exports.buildAllEventDecoders = buildAllEventDecoders;
 exports.buildAllMessageDecoders = buildAllMessageDecoders;
 exports.buildEventDecoder = buildEventDecoder;
+exports.buildLabelMap = buildLabelMap;
 exports.buildMessageDecoder = buildMessageDecoder;
+exports.buildSelectorMap = buildSelectorMap;
 exports.compareGasWeight = compareGasWeight;
 exports.createAsciiEventTopic = createAsciiEventTopic;
 exports.createCodecRegistry = createCodecRegistry;
 exports.createContractEventStream = createContractEventStream;
 exports.createD9InkContract = createD9InkContract;
 exports.createD9InkSdk = createD9InkSdk;
+exports.createExtrinsicParser = createExtrinsicParser;
 exports.createMessageBuilder = createMessageBuilder;
 exports.createNativeTransferStream = createNativeTransferStream;
 exports.createPSP22TransferStream = createPSP22TransferStream;
@@ -1915,10 +2517,18 @@ exports.encodeCall = encodeCall;
 exports.encodeContractCall = encodeContractCall;
 exports.encodeContractCallWithLimits = encodeContractCallWithLimits;
 exports.estimateTransactionCost = estimateTransactionCost;
+exports.extractContractEmittedData = extractContractEmittedData;
 exports.formatGasInfo = formatGasInfo;
 exports.gasExceedsLimit = gasExceedsLimit;
+exports.getAllSelectors = getAllSelectors;
 exports.getEventSignature = getEventSignature;
+exports.getLabelForSelector = getLabelForSelector;
+exports.getSelectorForLabel = getSelectorForLabel;
+exports.isApplyExtrinsicPhase = isApplyExtrinsicPhase;
+exports.isBalancesTransferEvent = isBalancesTransferEvent;
 exports.isCallType = isCallType;
+exports.isContractCalledEvent = isContractCalledEvent;
+exports.isContractEmittedEvent = isContractEmittedEvent;
 Object.defineProperty(exports, 'isContractError', {
   enumerable: true,
   get: function () {
@@ -1933,5 +2543,7 @@ Object.defineProperty(exports, 'isErrorType', {
 });
 exports.isEventType = isEventType;
 exports.isLangError = isLangError;
+exports.isMessageCall = isMessageCall;
+exports.isPSP22Call = isPSP22Call;
 exports.unwrapInkResult = unwrapInkResult;
 //# sourceMappingURL=index.cjs.map