@haneullabs/haneul 0.1.0

package/src/cryptography/intent.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '../bcs/index.js';
+
+export type IntentScope = Exclude<keyof typeof bcs.IntentScope.$inferType, '$kind'>;
+/**
+ * Inserts a domain separator for a message that is being signed
+ */
+export function messageWithIntent(scope: IntentScope, message: Uint8Array) {
+	return bcs
+		.IntentMessage(bcs.bytes(message.length))
+		.serialize({
+			intent: {
+				scope: { [scope as 'PersonalMessage']: true },
+				version: { V0: true },
+				appId: { Sui: true },
+			},
+			value: message,
+		})
+		.toBytes();
+}

package/src/cryptography/keypair.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs, toBase64 } from '@haneullabs/bcs';
+import { blake2b } from '@noble/hashes/blake2b';
+import { bech32 } from '@scure/base';
+
+import type { IntentScope } from './intent.js';
+import { messageWithIntent } from './intent.js';
+import type { PublicKey } from './publickey.js';
+import { SIGNATURE_FLAG_TO_SCHEME, SIGNATURE_SCHEME_TO_FLAG } from './signature-scheme.js';
+import type { SignatureScheme } from './signature-scheme.js';
+import { toSerializedSignature } from './signature.js';
+import type { Transaction } from '../transactions/Transaction.js';
+import type { ClientWithCoreApi, Experimental_HaneulClientTypes } from '../experimental/index.js';
+
+export const PRIVATE_KEY_SIZE = 32;
+export const LEGACY_PRIVATE_KEY_SIZE = 64;
+export const SUI_PRIVATE_KEY_PREFIX = 'suiprivkey';
+
+export type ParsedKeypair = {
+	scheme: SignatureScheme;
+	/** @deprecated use `scheme` instead */
+	schema: SignatureScheme;
+	secretKey: Uint8Array;
+};
+
+export interface SignatureWithBytes {
+	bytes: string;
+	signature: string;
+}
+
+export interface SignAndExecuteOptions {
+	transaction: Transaction;
+	client: ClientWithCoreApi;
+}
+
+/**
+ * TODO: Document
+ */
+export abstract class Signer {
+	abstract sign(bytes: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+	/**
+	 * Sign messages with a specific intent. By combining the message bytes with the intent before hashing and signing,
+	 * it ensures that a signed message is tied to a specific purpose and domain separator is provided
+	 */
+	async signWithIntent(bytes: Uint8Array, intent: IntentScope): Promise<SignatureWithBytes> {
+		const intentMessage = messageWithIntent(intent, bytes);
+		const digest = blake2b(intentMessage, { dkLen: 32 });
+
+		const signature = toSerializedSignature({
+			signature: await this.sign(digest),
+			signatureScheme: this.getKeyScheme(),
+			publicKey: this.getPublicKey(),
+		});
+
+		return {
+			signature,
+			bytes: toBase64(bytes),
+		};
+	}
+	/**
+	 * Signs provided transaction by calling `signWithIntent()` with a `TransactionData` provided as intent scope
+	 */
+	async signTransaction(bytes: Uint8Array) {
+		return this.signWithIntent(bytes, 'TransactionData');
+	}
+	/**
+	 * Signs provided personal message by calling `signWithIntent()` with a `PersonalMessage` provided as intent scope
+	 */
+	async signPersonalMessage(bytes: Uint8Array) {
+		const { signature } = await this.signWithIntent(
+			bcs.byteVector().serialize(bytes).toBytes(),
+			'PersonalMessage',
+		);
+
+		return {
+			bytes: toBase64(bytes),
+			signature,
+		};
+	}
+
+	async signAndExecuteTransaction({
+		transaction,
+		client,
+	}: SignAndExecuteOptions): Promise<
+		Omit<Experimental_HaneulClientTypes.TransactionResponse, 'balanceChanges'>
+	> {
+		const bytes = await transaction.build({ client });
+		const { signature } = await this.signTransaction(bytes);
+		const response = await client.core.executeTransaction({
+			transaction: bytes,
+			signatures: [signature],
+		});
+
+		return response.transaction;
+	}
+
+	toHaneulAddress(): string {
+		return this.getPublicKey().toHaneulAddress();
+	}
+
+	/**
+	 * Get the key scheme of the keypair: Secp256k1 or ED25519
+	 */
+	abstract getKeyScheme(): SignatureScheme;
+
+	/**
+	 * The public key for this keypair
+	 */
+	abstract getPublicKey(): PublicKey;
+}
+
+export abstract class Keypair extends Signer {
+	/**
+	 * This returns the Bech32 secret key string for this keypair.
+	 */
+	abstract getSecretKey(): string;
+}
+
+/**
+ * This returns an ParsedKeypair object based by validating the
+ * 33-byte Bech32 encoded string starting with `suiprivkey`, and
+ * parse out the signature scheme and the private key in bytes.
+ */
+export function decodeHaneulPrivateKey(value: string): ParsedKeypair {
+	const { prefix, words } = bech32.decode(value as `${string}1${string}`);
+	if (prefix !== SUI_PRIVATE_KEY_PREFIX) {
+		throw new Error('invalid private key prefix');
+	}
+	const extendedSecretKey = new Uint8Array(bech32.fromWords(words));
+	const secretKey = extendedSecretKey.slice(1);
+	const signatureScheme =
+		SIGNATURE_FLAG_TO_SCHEME[extendedSecretKey[0] as keyof typeof SIGNATURE_FLAG_TO_SCHEME];
+
+	return {
+		scheme: signatureScheme,
+		schema: signatureScheme,
+		secretKey: secretKey,
+	};
+}
+
+/**
+ * This returns a Bech32 encoded string starting with `suiprivkey`,
+ * encoding 33-byte `flag || bytes` for the given the 32-byte private
+ * key and its signature scheme.
+ */
+export function encodeHaneulPrivateKey(bytes: Uint8Array, scheme: SignatureScheme): string {
+	if (bytes.length !== PRIVATE_KEY_SIZE) {
+		throw new Error('Invalid bytes length');
+	}
+	const flag = SIGNATURE_SCHEME_TO_FLAG[scheme];
+	const privKeyBytes = new Uint8Array(bytes.length + 1);
+	privKeyBytes.set([flag]);
+	privKeyBytes.set(bytes, 1);
+	return bech32.encode(SUI_PRIVATE_KEY_PREFIX, bech32.toWords(privKeyBytes));
+}

package/src/cryptography/mnemonics.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+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}'.
+ *
+ * @param path path string (e.g. `m/44'/784'/0'/0'/0'`).
+ */
+export function isValidHardenedPath(path: string): boolean {
+	if (!new RegExp("^m\\/44'\\/784'\\/[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.
+ *
+ * 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`).
+ */
+export function isValidBIP32Path(path: string): boolean {
+	if (!new RegExp("^m\\/(54|74)'\\/784'\\/[0-9]+'\\/[0-9]+\\/[0-9]+$").test(path)) {
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Uses KDF to derive 64 bytes of key data from mnemonic with empty password.
+ *
+ * @param mnemonics 12 words string split by spaces.
+ */
+export function mnemonicToSeed(mnemonics: string): Uint8Array {
+	return bip39MnemonicToSeedSync(mnemonics, '');
+}
+
+/**
+ * Derive the seed in hex format from a 12-word mnemonic string.
+ *
+ * @param mnemonics 12 words string split by spaces.
+ */
+export function mnemonicToSeedHex(mnemonics: string): string {
+	return toHex(mnemonicToSeed(mnemonics));
+}

package/src/cryptography/publickey.ts

@@ -0,0 +1,168 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromBase64, toBase64 } from '@haneullabs/bcs';
+import { blake2b } from '@noble/hashes/blake2b';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import { bcs } from '../bcs/index.js';
+import { normalizeHaneulAddress, HANEUL_ADDRESS_LENGTH } from '../utils/haneul-types.js';
+import type { IntentScope } from './intent.js';
+import { messageWithIntent } from './intent.js';
+import { SIGNATURE_FLAG_TO_SCHEME, SIGNATURE_SCHEME_TO_SIZE } from './signature-scheme.js';
+
+/**
+ * Value to be converted into public key.
+ */
+export type PublicKeyInitData = string | Uint8Array | Iterable<number>;
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array) {
+	if (a === b) return true;
+
+	if (a.length !== b.length) {
+		return false;
+	}
+
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * A public key
+ */
+export abstract class PublicKey {
+	/**
+	 * Checks if two public keys are equal
+	 */
+	equals(publicKey: PublicKey) {
+		return bytesEqual(this.toRawBytes(), publicKey.toRawBytes());
+	}
+
+	/**
+	 * Return the base-64 representation of the public key
+	 */
+	toBase64() {
+		return toBase64(this.toRawBytes());
+	}
+
+	toString(): never {
+		throw new Error(
+			'`toString` is not implemented on public keys. Use `toBase64()` or `toRawBytes()` instead.',
+		);
+	}
+
+	/**
+	 * Return the Haneul representation of the public key encoded in
+	 * base-64. A Sui public key is formed by the concatenation
+	 * of the scheme flag with the raw bytes of the public key
+	 */
+	toHaneulPublicKey(): string {
+		const bytes = this.toHaneulBytes();
+		return toBase64(bytes);
+	}
+
+	verifyWithIntent(
+		bytes: Uint8Array,
+		signature: Uint8Array | string,
+		intent: IntentScope,
+	): Promise<boolean> {
+		const intentMessage = messageWithIntent(intent, bytes);
+		const digest = blake2b(intentMessage, { dkLen: 32 });
+
+		return this.verify(digest, signature);
+	}
+
+	/**
+	 * Verifies that the signature is valid for for the provided PersonalMessage
+	 */
+	verifyPersonalMessage(message: Uint8Array, signature: Uint8Array | string): Promise<boolean> {
+		return this.verifyWithIntent(
+			bcs.byteVector().serialize(message).toBytes(),
+			signature,
+			'PersonalMessage',
+		);
+	}
+
+	/**
+	 * Verifies that the signature is valid for for the provided Transaction
+	 */
+	verifyTransaction(transaction: Uint8Array, signature: Uint8Array | string): Promise<boolean> {
+		return this.verifyWithIntent(transaction, signature, 'TransactionData');
+	}
+
+	/**
+	 * Verifies that the public key is associated with the provided address
+	 */
+	verifyAddress(address: string): boolean {
+		return this.toHaneulAddress() === address;
+	}
+
+	/**
+	 * Returns the bytes representation of the public key
+	 * prefixed with the signature scheme flag
+	 */
+	toHaneulBytes(): Uint8Array<ArrayBuffer> {
+		const rawBytes = this.toRawBytes();
+		const suiBytes = new Uint8Array(rawBytes.length + 1);
+		suiBytes.set([this.flag()]);
+		suiBytes.set(rawBytes, 1);
+
+		return suiBytes;
+	}
+
+	/**
+	 * Return the Haneul address associated with this Ed25519 public key
+	 */
+	toHaneulAddress(): string {
+		// Each hex char represents half a byte, hence hex address doubles the length
+		return normalizeHaneulAddress(
+			bytesToHex(blake2b(this.toHaneulBytes(), { dkLen: 32 })).slice(0, HANEUL_ADDRESS_LENGTH * 2),
+		);
+	}
+
+	/**
+	 * Return the byte array representation of the public key
+	 */
+	abstract toRawBytes(): Uint8Array<ArrayBuffer>;
+
+	/**
+	 * Return signature scheme flag of the public key
+	 */
+	abstract flag(): number;
+
+	/**
+	 * Verifies that the signature is valid for for the provided message
+	 */
+	abstract verify(data: Uint8Array, signature: Uint8Array | string): Promise<boolean>;
+}
+
+export function parseSerializedKeypairSignature(serializedSignature: string) {
+	const bytes = fromBase64(serializedSignature);
+
+	const signatureScheme =
+		SIGNATURE_FLAG_TO_SCHEME[bytes[0] as keyof typeof SIGNATURE_FLAG_TO_SCHEME];
+
+	switch (signatureScheme) {
+		case 'ED25519':
+		case 'Secp256k1':
+		case 'Secp256r1':
+			const size =
+				SIGNATURE_SCHEME_TO_SIZE[signatureScheme as keyof typeof SIGNATURE_SCHEME_TO_SIZE];
+			const signature = bytes.slice(1, bytes.length - size);
+			const publicKey = bytes.slice(1 + signature.length);
+
+			return {
+				serializedSignature,
+				signatureScheme,
+				signature,
+				publicKey,
+				bytes,
+			};
+		default:
+			throw new Error('Unsupported signature scheme');
+	}
+}

package/src/cryptography/signature-scheme.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export const SIGNATURE_SCHEME_TO_FLAG = {
+	ED25519: 0x00,
+	Secp256k1: 0x01,
+	Secp256r1: 0x02,
+	MultiSig: 0x03,
+	ZkLogin: 0x05,
+	Passkey: 0x06,
+} as const;
+
+export const SIGNATURE_SCHEME_TO_SIZE = {
+	ED25519: 32,
+	Secp256k1: 33,
+	Secp256r1: 33,
+	Passkey: 33,
+};
+
+export const SIGNATURE_FLAG_TO_SCHEME = {
+	0x00: 'ED25519',
+	0x01: 'Secp256k1',
+	0x02: 'Secp256r1',
+	0x03: 'MultiSig',
+	0x05: 'ZkLogin',
+	0x06: 'Passkey',
+} as const;
+
+export type SignatureScheme =
+	| 'ED25519'
+	| 'Secp256k1'
+	| 'Secp256r1'
+	| 'MultiSig'
+	| 'ZkLogin'
+	| 'Passkey';
+
+export type SignatureFlag = keyof typeof SIGNATURE_FLAG_TO_SCHEME;

package/src/cryptography/signature.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromBase64, toBase64 } from '@haneullabs/bcs';
+
+import { bcs } from '../bcs/index.js';
+import { parseSerializedPasskeySignature } from '../keypairs/passkey/publickey.js';
+import type { MultiSigStruct } from '../multisig/publickey.js';
+import { parseSerializedZkLoginSignature } from '../zklogin/publickey.js';
+import { parseSerializedKeypairSignature } from './publickey.js';
+import type { PublicKey } from './publickey.js';
+import type { SignatureScheme } from './signature-scheme.js';
+import { SIGNATURE_FLAG_TO_SCHEME, SIGNATURE_SCHEME_TO_FLAG } from './signature-scheme.js';
+
+/**
+ * Pair of signature and corresponding public key
+ */
+export type SerializeSignatureInput = {
+	signatureScheme: SignatureScheme;
+	/** Base64-encoded signature */
+	signature: Uint8Array;
+	/** Base64-encoded public key */
+	publicKey?: PublicKey;
+};
+
+/**
+ * Takes in a signature, its associated signing scheme and a public key, then serializes this data
+ */
+export function toSerializedSignature({
+	signature,
+	signatureScheme,
+	publicKey,
+}: SerializeSignatureInput): string {
+	if (!publicKey) {
+		throw new Error('`publicKey` is required');
+	}
+
+	const pubKeyBytes = publicKey.toRawBytes();
+	const serializedSignature = new Uint8Array(1 + signature.length + pubKeyBytes.length);
+	serializedSignature.set([SIGNATURE_SCHEME_TO_FLAG[signatureScheme]]);
+	serializedSignature.set(signature, 1);
+	serializedSignature.set(pubKeyBytes, 1 + signature.length);
+	return toBase64(serializedSignature);
+}
+
+/**
+ * Decodes a serialized signature into its constituent components: the signature scheme, the actual signature, and the public key
+ */
+export function parseSerializedSignature(serializedSignature: string) {
+	const bytes = fromBase64(serializedSignature);
+
+	const signatureScheme =
+		SIGNATURE_FLAG_TO_SCHEME[bytes[0] as keyof typeof SIGNATURE_FLAG_TO_SCHEME];
+
+	switch (signatureScheme) {
+		case 'Passkey':
+			return parseSerializedPasskeySignature(serializedSignature);
+		case 'MultiSig':
+			const multisig: MultiSigStruct = bcs.MultiSig.parse(bytes.slice(1));
+			return {
+				serializedSignature,
+				signatureScheme,
+				multisig,
+				bytes,
+				signature: undefined,
+			};
+		case 'ZkLogin':
+			return parseSerializedZkLoginSignature(serializedSignature);
+		case 'ED25519':
+		case 'Secp256k1':
+		case 'Secp256r1':
+			return parseSerializedKeypairSignature(serializedSignature);
+		default:
+			throw new Error('Unsupported signature scheme');
+	}
+}

package/src/experimental/cache.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export interface ClientCacheOptions {
+	prefix?: string[];
+	cache?: Map<string, unknown>;
+}
+
+export class ClientCache {
+	#prefix: string[];
+	#cache: Map<string, unknown>;
+
+	constructor({ prefix, cache }: ClientCacheOptions = {}) {
+		this.#prefix = prefix ?? [];
+		this.#cache = cache ?? new Map();
+	}
+
+	read<T>(key: [string, ...string[]], load: () => T | Promise<T>): T | Promise<T> {
+		const cacheKey = [this.#prefix, ...key].join(':');
+
+		if (this.#cache.has(cacheKey)) {
+			return this.#cache.get(cacheKey) as T;
+		}
+
+		const result = load();
+
+		this.#cache.set(cacheKey, result);
+
+		if (typeof result === 'object' && result !== null && 'then' in result) {
+			return Promise.resolve(result)
+				.then((v) => {
+					this.#cache.set(cacheKey, v);
+					return v as T;
+				})
+				.catch((err) => {
+					this.#cache.delete(cacheKey);
+					throw err;
+				});
+		}
+
+		return result as T;
+	}
+
+	readSync<T>(key: [string, ...string[]], load: () => T): T {
+		const cacheKey = [this.#prefix, ...key].join(':');
+
+		if (this.#cache.has(cacheKey)) {
+			return this.#cache.get(cacheKey) as T;
+		}
+
+		const result = load();
+
+		this.#cache.set(cacheKey, result);
+
+		return result as T;
+	}
+
+	clear(prefix?: string[]) {
+		const prefixKey = [...this.#prefix, ...(prefix ?? [])].join(':');
+		if (!prefixKey) {
+			this.#cache.clear();
+			return;
+		}
+
+		for (const key of this.#cache.keys()) {
+			if (key.startsWith(prefixKey)) {
+				this.#cache.delete(key);
+			}
+		}
+	}
+
+	scope(prefix: string | string[]) {
+		return new ClientCache({
+			prefix: [...this.#prefix, ...(Array.isArray(prefix) ? prefix : [prefix])],
+			cache: this.#cache,
+		});
+	}
+}

package/src/experimental/client.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type { Simplify, UnionToIntersection } from '@haneullabs/utils';
+import { ClientCache } from './cache.js';
+import type { Experimental_CoreClient } from './core.js';
+import type {
+	ClientWithExtensions,
+	Experimental_HaneulClientTypes,
+	HaneulClientRegistration,
+} from './types.js';
+
+export abstract class Experimental_BaseClient {
+	network: Experimental_HaneulClientTypes.Network;
+	cache: ClientCache;
+	base: Experimental_BaseClient;
+
+	constructor({
+		network,
+		base,
+		cache = base?.cache ?? new ClientCache(),
+	}: Experimental_HaneulClientTypes.HaneulClientOptions) {
+		this.network = network;
+		this.base = base ?? this;
+		this.cache = cache;
+	}
+
+	abstract core: Experimental_CoreClient;
+
+	$extend<const Registrations extends HaneulClientRegistration<this>[]>(
+		...registrations: Registrations
+	) {
+		return Object.create(
+			this,
+			Object.fromEntries(
+				registrations.map((registration) => {
+					return [registration.name, { value: registration.register(this) }];
+				}),
+			),
+		) as ClientWithExtensions<
+			Simplify<
+				UnionToIntersection<
+					{
+						[K in keyof Registrations]: Registrations[K] extends HaneulClientRegistration<
+							this,
+							infer Name extends string,
+							infer Extension
+						>
+							? {
+									[K2 in Name]: Extension;
+								}
+							: never;
+					}[number]
+				>
+			>,
+			this
+		>;
+	}
+}