near-kit 0.4.5 → 0.5.0

package/dist/utils/state-init.js

@@ -0,0 +1,208 @@
+/**
+ * NEP-616 StateInit utilities for deterministic account IDs
+ *
+ * This module provides utilities for working with NEP-616 Deterministic AccountIds.
+ * These account IDs are derived from the contract initialization state using the formula:
+ * `"0s" + hex(keccak256(borsh(state_init))[12..32])`
+ *
+ * @see https://github.com/near/NEPs/pull/616
+ */
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { base58, hex } from "@scure/base";
+import { b } from "@zorsh/zorsh";
+// ==================== Helper Functions ====================
+/**
+ * Parse and validate a code hash from either base58 string or Uint8Array
+ *
+ * @param codeHash - Code hash as base58 string or Uint8Array
+ * @returns Validated 32-byte hash as Uint8Array
+ * @throws Error if base58 is invalid or hash is not 32 bytes
+ */
+export function parseCodeHash(codeHash) {
+    let hashBytes;
+    if (typeof codeHash === "string") {
+        try {
+            hashBytes = base58.decode(codeHash);
+        }
+        catch {
+            throw new Error(`Invalid base58 code hash: ${codeHash}`);
+        }
+    }
+    else {
+        hashBytes = codeHash;
+    }
+    if (hashBytes.length !== 32) {
+        throw new Error(`Code hash must be 32 bytes, got ${hashBytes.length} bytes`);
+    }
+    return hashBytes;
+}
+// ==================== Borsh Schemas for StateInit ====================
+/**
+ * GlobalContractIdentifier enum for Borsh serialization
+ * 0 = CodeHash (32-byte hash)
+ * 1 = AccountId (string)
+ */
+const GlobalContractIdentifierSchema = b.enum({
+    CodeHash: b.array(b.u8(), 32),
+    AccountId: b.string(),
+});
+/**
+ * StateInitV1 struct for Borsh serialization
+ */
+const StateInitV1Schema = b.struct({
+    code: GlobalContractIdentifierSchema,
+    data: b.hashMap(b.bytes(), b.bytes()),
+});
+/**
+ * StateInit enum (versioned) for Borsh serialization
+ */
+const StateInitSchema = b.enum({
+    V1: StateInitV1Schema,
+});
+/**
+ * Create a StateInit object from options
+ *
+ * @param options - StateInit configuration
+ * @returns StateInit object
+ */
+export function createStateInit(options) {
+    let code;
+    if ("accountId" in options.code) {
+        code = { type: "accountId", accountId: options.code.accountId };
+    }
+    else {
+        const hashBytes = parseCodeHash(options.code.codeHash);
+        code = { type: "codeHash", hash: hashBytes };
+    }
+    return {
+        code,
+        data: options.data ?? new Map(),
+    };
+}
+/**
+ * Serialize a StateInit to Borsh bytes
+ *
+ * @param stateInit - StateInit object to serialize
+ * @returns Borsh-serialized bytes
+ */
+export function serializeStateInit(stateInit) {
+    let codeIdentifier;
+    if (stateInit.code.type === "accountId") {
+        codeIdentifier = { AccountId: stateInit.code.accountId };
+    }
+    else {
+        codeIdentifier = { CodeHash: Array.from(stateInit.code.hash) };
+    }
+    // Sort the data map by keys to ensure deterministic serialization
+    // NEP-616 specifies BTreeMap which has sorted order, but JavaScript Map
+    // maintains insertion order. We must sort to ensure the same key-value pairs
+    // produce the same account ID regardless of insertion order.
+    const sortedData = new Map(Array.from(stateInit.data.entries()).sort((a, b) => {
+        const [keyA] = a;
+        const [keyB] = b;
+        // Compare byte-by-byte
+        for (let i = 0; i < Math.min(keyA.length, keyB.length); i++) {
+            const byteA = keyA[i];
+            const byteB = keyB[i];
+            if (byteA !== undefined && byteB !== undefined && byteA !== byteB) {
+                return byteA - byteB;
+            }
+        }
+        // If all bytes match, shorter key comes first
+        return keyA.length - keyB.length;
+    }));
+    return StateInitSchema.serialize({
+        V1: {
+            code: codeIdentifier,
+            data: sortedData,
+        },
+    });
+}
+/**
+ * Derive a deterministic account ID from a StateInit according to NEP-616.
+ *
+ * The account ID is derived as: `"0s" + hex(keccak256(borsh(state_init))[12..32])`
+ *
+ * This produces a 42-character account ID that:
+ * - Starts with "0s" prefix (distinguishes from Ethereum implicit accounts "0x")
+ * - Followed by 40 hex characters (20 bytes from the keccak256 hash)
+ *
+ * @param stateInit - StateInit object or options to create one
+ * @returns The deterministically derived account ID
+ *
+ * @example
+ * ```typescript
+ * // From a global contract by account ID
+ * const accountId = deriveAccountId({
+ *   code: { accountId: "publisher.near" },
+ * })
+ * // => "0s1234567890abcdef1234567890abcdef12345678"
+ *
+ * // From a global contract by code hash
+ * const accountId = deriveAccountId({
+ *   code: { codeHash: hashBytes },
+ * })
+ *
+ * // With initial storage data
+ * const accountId = deriveAccountId({
+ *   code: { accountId: "publisher.near" },
+ *   data: new Map([[key1, value1], [key2, value2]]),
+ * })
+ * ```
+ */
+export function deriveAccountId(options) {
+    const stateInit = createStateInit(options);
+    const serialized = serializeStateInit(stateInit);
+    const hash = keccak_256(serialized);
+    // Take last 20 bytes (indices 12-32) of the hash
+    const suffix = hash.slice(12, 32);
+    return `0s${hex.encode(suffix)}`;
+}
+/**
+ * Verify that an account ID matches the expected deterministic derivation from a StateInit.
+ *
+ * @param accountId - The account ID to verify
+ * @param options - StateInit options to derive the expected account ID from
+ * @returns true if the account ID matches the derivation, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = verifyDeterministicAccountId(
+ *   "0s1234567890abcdef1234567890abcdef12345678",
+ *   { code: { accountId: "publisher.near" } }
+ * )
+ * ```
+ */
+export function verifyDeterministicAccountId(accountId, options) {
+    const expected = deriveAccountId(options);
+    return accountId === expected;
+}
+/**
+ * Check if an account ID is a deterministic account ID (NEP-616).
+ *
+ * Deterministic account IDs start with "0s" followed by 40 hex characters.
+ *
+ * @param accountId - The account ID to check
+ * @returns true if it's a deterministic account ID, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isDeterministicAccountId("0s1234567890abcdef1234567890abcdef12345678") // true
+ * isDeterministicAccountId("alice.near") // false
+ * isDeterministicAccountId("0x1234567890abcdef1234567890abcdef12345678") // false (Ethereum)
+ * ```
+ */
+export function isDeterministicAccountId(accountId) {
+    // Must be exactly 42 characters: "0s" + 40 hex chars
+    if (accountId.length !== 42) {
+        return false;
+    }
+    // Must start with "0s"
+    if (!accountId.startsWith("0s")) {
+        return false;
+    }
+    // Rest must be valid hex
+    const hexPart = accountId.slice(2);
+    return /^[0-9a-f]+$/.test(hexPart);
+}
+//# sourceMappingURL=state-init.js.map

package/dist/utils/state-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-init.js","sourceRoot":"","sources":["../../src/utils/state-init.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-kit",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "A simple, intuitive TypeScript library for interacting with NEAR Protocol",
   "type": "module",
   "main": "./dist/index.js",
@@ -67,7 +67,7 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.7",
+    "@biomejs/biome": "2.3.8",
     "@changesets/cli": "^2.29.7",
     "@hot-labs/near-connect": "^0.6.9",
     "@near-js/transactions": "^2.5.1",