@haneullabs/haneul 2.5.2 → 2.13.0

package/src/client/types.ts

@@ -58,24 +58,54 @@ export namespace HaneulClientTypes {
 	}
 
 	export interface ObjectInclude {
+		/**
+		 * Include the BCS-encoded Move struct content of the object.
+		 *
+		 * Returns the raw bytes of the object's Move struct fields — pass directly to
+		 * generated BCS types (e.g., `MyStruct.parse(object.content)`).
+		 */
 		content?: boolean;
+		/**
+		 * Include the digest of the transaction that last mutated this object.
+		 */
 		previousTransaction?: boolean;
+		/**
+		 * Include the full BCS-encoded object envelope. Rarely needed — most metadata
+		 * (owner, version, type) is already available as fields on the object response.
+		 *
+		 * Parse with `bcs.Object.parse(object.objectBcs)` from `@haneullabs/haneul/bcs`.
+		 * Do not pass to a Move struct parser — use `content` for that instead.
+		 */
 		objectBcs?: boolean;
+		/**
+		 * Include the JSON representation of the object's Move struct content.
+		 *
+		 * **Warning:** The exact shape and field names of this data may vary between different
+		 * API implementations (JSON-RPC vs gRPC or GraphQL). For consistent data across APIs,
+		 * use the `content` field and parse the BCS data directly.
+		 */
 		json?: boolean;
+		/**
+		 * Include the Display v2 rendered output for the object.
+		 *
+		 * Returns a map of display field names to their rendered string values.
+		 * Returns `null` if the object's type does not have an associated Display template.
+		 */
+		display?: boolean;
 	}
 
 	export interface GetObjectsOptions<
 		Include extends ObjectInclude = {},
 	> extends CoreClientMethodOptions {
 		objectIds: string[];
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface GetObjectOptions<
 		Include extends ObjectInclude = {},
 	> extends CoreClientMethodOptions {
 		objectId: string;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface ListOwnedObjectsOptions<
@@ -85,7 +115,7 @@ export namespace HaneulClientTypes {
 		limit?: number;
 		cursor?: string | null;
 		type?: string;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface ListCoinsOptions extends CoreClientMethodOptions {
@@ -133,8 +163,10 @@ export namespace HaneulClientTypes {
 		digest: string;
 		owner: ObjectOwner;
 		type: string;
+		/** BCS-encoded Move struct content — pass to generated BCS type parsers. */
 		content: Include extends { content: true } ? Uint8Array<ArrayBuffer> : undefined;
 		previousTransaction: Include extends { previousTransaction: true } ? string | null : undefined;
+		/** Full BCS-encoded object envelope — parse with `bcs.Object` not a struct parser. */
 		objectBcs: Include extends { objectBcs: true } ? Uint8Array<ArrayBuffer> : undefined;
 		/**
 		 * The JSON representation of the object's Move struct content.
@@ -144,6 +176,15 @@ export namespace HaneulClientTypes {
 		 * the `content` field and parse the BCS data directly.
 		 */
 		json: Include extends { json: true } ? Record<string, unknown> | null : undefined;
+		/** Display rendered output. `null` if the type has no Display template. */
+		display: Include extends { display: true } ? Display | null : undefined;
+	}
+
+	export interface Display {
+		/** Successfully rendered display field values, keyed by field name. */
+		output: Record<string, string> | null;
+		/** Per-field rendering errors, keyed by field name. `null` if all fields succeeded. */
+		errors: Record<string, string> | null;
 	}
 
 	export interface Coin {
@@ -155,27 +196,28 @@ export namespace HaneulClientTypes {
 		balance: string;
 	}
 
+	export type DynamicFieldEntry = {
+		fieldId: string;
+		type: string;
+		name: DynamicFieldName;
+		valueType: string;
+	} & ({ $kind: 'DynamicField'; childId?: never } | { $kind: 'DynamicObject'; childId: string });
+
+	export type DynamicField = DynamicFieldEntry & {
+		value: DynamicFieldValue;
+		version: string;
+		digest: string;
+		previousTransaction: string | null;
+	};
+
 	export interface ListDynamicFieldsResponse {
 		hasNextPage: boolean;
 		cursor: string | null;
-		dynamicFields: {
-			fieldId: string;
-			type: string;
-			name: DynamicFieldName;
-			valueType: string;
-		}[];
+		dynamicFields: DynamicFieldEntry[];
 	}
 
 	export interface GetDynamicFieldResponse {
-		dynamicField: {
-			name: DynamicFieldName;
-			value: DynamicFieldValue;
-			fieldId: string;
-			version: string;
-			digest: string;
-			type: string;
-			previousTransaction: string | null;
-		};
+		dynamicField: DynamicField;
 	}
 
 	export interface GetDynamicObjectFieldOptions<
@@ -183,7 +225,7 @@ export namespace HaneulClientTypes {
 	> extends CoreClientMethodOptions {
 		parentId: string;
 		name: DynamicFieldName;
-		include?: Include;
+		include?: Include & ObjectInclude;
 	}
 
 	export interface GetDynamicObjectFieldResponse<out Include extends ObjectInclude = {}> {
@@ -311,15 +353,22 @@ export namespace HaneulClientTypes {
 		  };
 
 	export interface TransactionInclude {
+		/** Include balance changes caused by the transaction. */
 		balanceChanges?: boolean;
+		/** Include parsed transaction effects (gas used, changed objects, status, etc.). */
 		effects?: boolean;
+		/** Include events emitted by the transaction. */
 		events?: boolean;
+		/** Include a map of object IDs to their types for all changed objects. */
 		objectTypes?: boolean;
+		/** Include the parsed transaction data (sender, gas config, inputs, commands). */
 		transaction?: boolean;
+		/** Include the raw BCS-encoded transaction bytes. */
 		bcs?: boolean;
 	}
 
 	export interface SimulateTransactionInclude extends TransactionInclude {
+		/** Include return values and mutated references from each command (simulation only). */
 		commandResults?: boolean;
 	}
 
@@ -344,7 +393,7 @@ export namespace HaneulClientTypes {
 		Include extends TransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		digest: string;
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export type WaitForTransactionOptions<Include extends TransactionInclude = {}> =
@@ -355,6 +404,8 @@ export namespace HaneulClientTypes {
 		Include extends TransactionInclude = {},
 	> extends GetTransactionOptions<Include> {
 		timeout?: number;
+		/** Absolute times (ms from start) to poll, e.g. [0, 300, 600, 1500]. After exhausted, repeats the last interval. */
+		pollSchedule?: number[];
 		result?: never;
 	}
 
@@ -362,8 +413,10 @@ export namespace HaneulClientTypes {
 		Include extends TransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		result: TransactionResult<any>;
-		include?: Include;
+		include?: Include & TransactionInclude;
 		timeout?: number;
+		/** Absolute times (ms from start) to poll, e.g. [0, 300, 600, 1500]. After exhausted, repeats the last interval. */
+		pollSchedule?: number[];
 		digest?: never;
 	}
 
@@ -372,7 +425,7 @@ export namespace HaneulClientTypes {
 	> extends CoreClientMethodOptions {
 		transaction: Uint8Array;
 		signatures: string[];
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export interface SignAndExecuteTransactionOptions<
@@ -381,14 +434,22 @@ export namespace HaneulClientTypes {
 		transaction: Uint8Array | TransactionInstance;
 		signer: Signer;
 		additionalSignatures?: string[];
-		include?: Include;
+		include?: Include & TransactionInclude;
 	}
 
 	export interface SimulateTransactionOptions<
 		Include extends SimulateTransactionInclude = {},
 	> extends CoreClientMethodOptions {
 		transaction: Uint8Array | TransactionInstance;
-		include?: Include;
+		include?: Include & SimulateTransactionInclude;
+		/**
+		 * When set to `false`, disables transaction validation checks during simulation.
+		 * This allows inspecting non-public/non-entry Move functions and other transactions
+		 * that would normally fail validation.
+		 *
+		 * Defaults to `true` (checks enabled).
+		 */
+		checksEnabled?: boolean;
 	}
 
 	export interface GetReferenceGasPriceOptions extends CoreClientMethodOptions {}
@@ -415,6 +476,22 @@ export namespace HaneulClientTypes {
 		systemState: SystemStateInfo;
 	}
 
+	export interface GetProtocolConfigOptions extends CoreClientMethodOptions {}
+
+	export interface TransportMethods {
+		getProtocolConfig?: (options?: GetProtocolConfigOptions) => Promise<GetProtocolConfigResponse>;
+	}
+
+	export interface GetProtocolConfigResponse {
+		protocolConfig: ProtocolConfig;
+	}
+
+	export interface ProtocolConfig {
+		protocolVersion: string;
+		featureFlags: Record<string, boolean>;
+		attributes: Record<string, string | null>;
+	}
+
 	export interface GetChainIdentifierOptions extends CoreClientMethodOptions {}
 
 	export interface TransportMethods {
@@ -814,6 +891,14 @@ export namespace HaneulClientTypes {
 		sender: string;
 		eventType: string;
 		bcs: Uint8Array;
+		/**
+		 * The JSON representation of the event's Move struct data.
+		 *
+		 * **Warning:** The exact shape and field names of this data may vary between different
+		 * API implementations (JSON-RPC vs gRPC or GraphQL). For consistent data across APIs use
+		 * the `bcs` field and parse the BCS data directly.
+		 */
+		json: Record<string, unknown> | null;
 	}
 
 	export interface MoveAbort {

package/src/cryptography/index.ts

@@ -29,8 +29,8 @@ export {
 	type SignatureWithBytes,
 	Signer,
 	Keypair,
-	decodeSuiPrivateKey,
-	encodeSuiPrivateKey,
+	decodeHaneulPrivateKey,
+	encodeHaneulPrivateKey,
 } from './keypair.js';
 
 export { PublicKey } from './publickey.js';

package/src/cryptography/keypair.ts

@@ -122,7 +122,7 @@ export abstract class Keypair extends Signer {
  * 33-byte Bech32 encoded string starting with `haneulprivkey`, and
  * parse out the signature scheme and the private key in bytes.
  */
-export function decodeSuiPrivateKey(value: string): ParsedKeypair {
+export function decodeHaneulPrivateKey(value: string): ParsedKeypair {
 	const { prefix, words } = bech32.decode(value as `${string}1${string}`);
 	if (prefix !== HANEUL_PRIVATE_KEY_PREFIX) {
 		throw new Error('invalid private key prefix');
@@ -143,7 +143,7 @@ export function decodeSuiPrivateKey(value: string): ParsedKeypair {
  * encoding 33-byte `flag || bytes` for the given the 32-byte private
  * key and its signature scheme.
  */
-export function encodeSuiPrivateKey(bytes: Uint8Array, scheme: SignatureScheme): string {
+export function encodeHaneulPrivateKey(bytes: Uint8Array, scheme: SignatureScheme): string {
 	if (bytes.length !== PRIVATE_KEY_SIZE) {
 		throw new Error('Invalid bytes length');
 	}

package/src/cryptography/mnemonics.ts

@@ -4,27 +4,27 @@ import { toHex } from '@haneullabs/bcs';
 import { mnemonicToSeedSync as bip39MnemonicToSeedSync } from '@scure/bip39';
 
 /**
- * Parse and validate a path that is compliant to SLIP-0010 in form m/44'/784'/{account_index}'/{change_index}'/{address_index}'.
+ * Parse and validate a path that is compliant to SLIP-0010 in form m/44'/8282'/{account_index}'/{change_index}'/{address_index}'.
  *
- * @param path path string (e.g. `m/44'/784'/0'/0'/0'`).
+ * @param path path string (e.g. `m/44'/8282'/0'/0'/0'`).
  */
 export function isValidHardenedPath(path: string): boolean {
-	if (!new RegExp("^m\\/44'\\/784'\\/[0-9]+'\\/[0-9]+'\\/[0-9]+'+$").test(path)) {
+	if (!new RegExp("^m\\/44'\\/8282'\\/[0-9]+'\\/[0-9]+'\\/[0-9]+'+$").test(path)) {
 		return false;
 	}
 	return true;
 }
 
 /**
- * Parse and validate a path that is compliant to BIP-32 in form m/54'/784'/{account_index}'/{change_index}/{address_index}
- * for Secp256k1 and m/74'/784'/{account_index}'/{change_index}/{address_index} for Secp256r1.
+ * Parse and validate a path that is compliant to BIP-32 in form m/54'/8282'/{account_index}'/{change_index}/{address_index}
+ * for Secp256k1 and m/74'/8282'/{account_index}'/{change_index}/{address_index} for Secp256r1.
  *
  * Note that the purpose for Secp256k1 is registered as 54, to differentiate from Ed25519 with purpose 44.
  *
- * @param path path string (e.g. `m/54'/784'/0'/0/0`).
+ * @param path path string (e.g. `m/54'/8282'/0'/0/0`).
  */
 export function isValidBIP32Path(path: string): boolean {
-	if (!new RegExp("^m\\/(54|74)'\\/784'\\/[0-9]+'\\/[0-9]+\\/[0-9]+$").test(path)) {
+	if (!new RegExp("^m\\/(54|74)'\\/8282'\\/[0-9]+'\\/[0-9]+\\/[0-9]+$").test(path)) {
 		return false;
 	}
 	return true;

package/src/cryptography/publickey.ts

@@ -60,7 +60,7 @@ export abstract class PublicKey {
 	 * base-64. A Haneul public key is formed by the concatenation
 	 * of the scheme flag with the raw bytes of the public key
 	 */
-	toSuiPublicKey(): string {
+	toHaneulPublicKey(): string {
 		const bytes = this.toHaneulBytes();
 		return toBase64(bytes);
 	}
@@ -107,11 +107,11 @@ export abstract class PublicKey {
 	 */
 	toHaneulBytes(): Uint8Array<ArrayBuffer> {
 		const rawBytes = this.toRawBytes();
-		const suiBytes = new Uint8Array(rawBytes.length + 1);
-		suiBytes.set([this.flag()]);
-		suiBytes.set(rawBytes, 1);
+		const haneulBytes = new Uint8Array(rawBytes.length + 1);
+		haneulBytes.set([this.flag()]);
+		haneulBytes.set(rawBytes, 1);
 
-		return suiBytes;
+		return haneulBytes;
 	}
 
 	/**

package/src/faucet/faucet.ts

@@ -55,7 +55,7 @@ async function faucetRequest<T>({ host, path, body, headers, method }: FaucetReq
 	}
 }
 
-export async function requestSuiFromFaucetV2(input: {
+export async function requestHaneulFromFaucetV2(input: {
 	host: string;
 	recipient: string;
 	headers?: HeadersInit;

package/src/faucet/index.ts

@@ -1,4 +1,4 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-export { requestSuiFromFaucetV2, getFaucetHost, FaucetRateLimitError } from './faucet.js';
+export { requestHaneulFromFaucetV2, getFaucetHost, FaucetRateLimitError } from './faucet.js';

package/src/graphql/client.ts

@@ -9,6 +9,10 @@ import { BaseClient } from '../client/index.js';
 import type { HaneulClientTypes } from '../client/index.js';
 import { GraphQLCoreClient } from './core.js';
 import type { TypedDocumentString } from './generated/queries.js';
+import { GetDynamicFieldsDocument } from './generated/queries.js';
+import { fromBase64 } from '@haneullabs/utils';
+import { normalizeStructTag } from '../utils/haneul-types.js';
+import { deriveDynamicFieldID } from '../utils/dynamic-fields.js';
 import type { TransactionPlugin } from '../transactions/index.js';
 
 export type GraphQLDocument<
@@ -58,14 +62,29 @@ export interface HaneulGraphQLClientOptions<Queries extends Record<string, Graph
 
 export class HaneulGraphQLRequestError extends Error {}
 
-const SUI_CLIENT_BRAND = Symbol.for('@haneullabs/HaneulGraphQLClient') as never;
+const HANEUL_CLIENT_BRAND = Symbol.for('@haneullabs/HaneulGraphQLClient') as never;
 
-export function isSuiGraphQLClient(client: unknown): client is HaneulGraphQLClient {
+export function isHaneulGraphQLClient(client: unknown): client is HaneulGraphQLClient {
 	return (
-		typeof client === 'object' && client !== null && (client as any)[SUI_CLIENT_BRAND] === true
+		typeof client === 'object' && client !== null && (client as any)[HANEUL_CLIENT_BRAND] === true
 	);
 }
 
+export interface DynamicFieldInclude {
+	value?: boolean;
+}
+
+export type DynamicFieldEntryWithValue<Include extends DynamicFieldInclude = {}> =
+	HaneulClientTypes.DynamicFieldEntry & {
+		value: Include extends { value: true } ? HaneulClientTypes.DynamicFieldValue : undefined;
+	};
+
+export interface ListDynamicFieldsWithValueResponse<Include extends DynamicFieldInclude = {}> {
+	hasNextPage: boolean;
+	cursor: string | null;
+	dynamicFields: DynamicFieldEntryWithValue<Include>[];
+}
+
 export class HaneulGraphQLClient<Queries extends Record<string, GraphQLDocument> = {}>
 	extends BaseClient
 	implements HaneulClientTypes.TransportMethods
@@ -79,7 +98,7 @@ export class HaneulGraphQLClient<Queries extends Record<string, GraphQLDocument>
 		return this.core.mvr;
 	}
 
-	get [SUI_CLIENT_BRAND]() {
+	get [HANEUL_CLIENT_BRAND]() {
 		return true;
 	}
 
@@ -220,10 +239,83 @@ export class HaneulGraphQLClient<Queries extends Record<string, GraphQLDocument>
 		return this.core.getReferenceGasPrice();
 	}
 
-	listDynamicFields(
-		input: HaneulClientTypes.ListDynamicFieldsOptions,
-	): Promise<HaneulClientTypes.ListDynamicFieldsResponse> {
-		return this.core.listDynamicFields(input);
+	async listDynamicFields<Include extends DynamicFieldInclude = {}>(
+		input: HaneulClientTypes.ListDynamicFieldsOptions & { include?: Include & DynamicFieldInclude },
+	): Promise<ListDynamicFieldsWithValueResponse<Include>> {
+		const includeValue = input.include?.value ?? false;
+
+		const { data, errors } = await this.query({
+			query: GetDynamicFieldsDocument,
+			variables: {
+				parentId: input.parentId,
+				first: input.limit,
+				cursor: input.cursor,
+				includeValue,
+			},
+		});
+
+		if (errors?.length) {
+			throw errors.length === 1
+				? new Error(errors[0].message)
+				: new AggregateError(errors.map((e) => new Error(e.message)));
+		}
+
+		const result = data?.address?.dynamicFields;
+		if (!result) {
+			throw new Error('Missing response data');
+		}
+
+		return {
+			dynamicFields: result.nodes.map((dynamicField): DynamicFieldEntryWithValue<Include> => {
+				const valueType =
+					dynamicField.value?.__typename === 'MoveObject'
+						? dynamicField.value.contents?.type?.repr!
+						: dynamicField.value?.type?.repr!;
+				const isDynamicObject = dynamicField.value?.__typename === 'MoveObject';
+				const derivedNameType = isDynamicObject
+					? `0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>`
+					: dynamicField.name?.type?.repr!;
+
+				let value: HaneulClientTypes.DynamicFieldValue | undefined;
+				if (includeValue) {
+					let valueBcs: Uint8Array;
+					if (dynamicField.value?.__typename === 'MoveValue') {
+						valueBcs = fromBase64(dynamicField.value.bcs ?? '');
+					} else if (dynamicField.value?.__typename === 'MoveObject') {
+						valueBcs = fromBase64(dynamicField.value.contents?.bcs ?? '');
+					} else {
+						valueBcs = new Uint8Array();
+					}
+					value = { type: valueType, bcs: valueBcs };
+				}
+
+				return {
+					$kind: isDynamicObject ? 'DynamicObject' : 'DynamicField',
+					fieldId: deriveDynamicFieldID(
+						input.parentId,
+						derivedNameType,
+						fromBase64(dynamicField.name?.bcs!),
+					),
+					type: normalizeStructTag(
+						isDynamicObject
+							? `0x2::dynamic_field::Field<0x2::dynamic_object_field::Wrapper<${dynamicField.name?.type?.repr}>,0x2::object::ID>`
+							: `0x2::dynamic_field::Field<${dynamicField.name?.type?.repr},${valueType}>`,
+					),
+					name: {
+						type: dynamicField.name?.type?.repr!,
+						bcs: fromBase64(dynamicField.name?.bcs!),
+					},
+					valueType,
+					childId:
+						isDynamicObject && dynamicField.value?.__typename === 'MoveObject'
+							? dynamicField.value.address
+							: undefined,
+					value: (includeValue ? value : undefined) as DynamicFieldEntryWithValue<Include>['value'],
+				} as DynamicFieldEntryWithValue<Include>;
+			}),
+			cursor: result.pageInfo.endCursor ?? null,
+			hasNextPage: result.pageInfo.hasNextPage,
+		};
 	}
 
 	getDynamicField(