near-encoding 1.1.7619 → 1.1.9071

package/README.md

@@ -6,60 +6,53 @@ Utility functions for encoding, decoding, and interacting with the NEAR blockcha
 
 npm install near-encoding
 
-## API
-
-### `encodeBase64(input: string): string`
+## Usage
 
-Encodes a UTF-8 string to Base64.
+### Base64 Encoding / Decoding
 
-import { encodeBase64 } from 'near-encoding';
+import { encodeBase64, decodeBase64 } from 'near-encoding';
 
 const encoded = encodeBase64('hello world');
+// "aGVsbG8gd29ybGQ="
 
----
-
-### `decodeBase64(input: string): string`
-
-Decodes a Base64 string back to UTF-8.
-
-import { decodeBase64 } from 'near-encoding';
-
-const decoded = decodeBase64('aGVsbG8gd29ybGQ=');
+const decoded = decodeBase64(encoded);
+// "hello world"
 
----
+### Encoding / Decoding Contract Arguments
 
-### `encodeArgs(args: Record<string, unknown>): Buffer`
+import { encodeArgs, decodeArgs } from 'near-encoding';
 
-Serializes a plain object into a UTF-8 encoded `Buffer` for use in NEAR contract calls.
+const encoded = encodeArgs({ token_id: '1', receiver_id: 'alice.near' });
+// Base64-encoded JSON string
 
-import { encodeArgs } from 'near-encoding';
+const decoded = decodeArgs(encoded);
+// { token_id: '1', receiver_id: 'alice.near' }
 
-const buffer = encodeArgs({ token_id: '123', receiver_id: 'alice.near' });
+### Generating a Key Pair
 
----
+import { generateKeyPair } from 'near-encoding';
 
-### `functionCall(options: FunctionCallOptions): Promise<nearApiJs.providers.FinalExecutionOutcome>`
+const keyPair = generateKeyPair();
+// { publicKey: 'ed25519:...', secretKey: 'ed25519:...' }
 
-Executes a change-method call on a NEAR contract.
+### Calling a Contract Function
 
 import { functionCall } from 'near-encoding';
 
-const outcome = await functionCall({
-  accountId: 'alice.near',
-  contractId: 'token.near',
-  methodName: 'transfer',
-  args: { receiver_id: 'bob.near', amount: '100' },
-});
-
----
-
-### `generateKeyPair(accountId: string): GeneratedKeyPair`
+const result = await functionCall(options);
 
-Generates a new key pair associated with the given account ID.
+`options` accepts a `FunctionCallOptions` object. The function returns a `Promise<FunctionCallResult>`.
 
-import { generateKeyPair } from 'near-encoding';
+## API
 
-const keyPair = generateKeyPair('alice.near');
+| Function | Signature |
+|---|---|
+| `encodeBase64` | `(input: string): string` |
+| `decodeBase64` | `(input: string): string` |
+| `encodeArgs` | `(args: Record<string, unknown>): string` |
+| `decodeArgs` | `(encoded: string): Record<string, unknown>` |
+| `generateKeyPair` | `(): KeyPairResult` |
+| `functionCall` | `(options: FunctionCallOptions): Promise<FunctionCallResult>` |
 
 ## License
 

package/index.js

@@ -4,102 +4,125 @@ import { KeyPairEd25519 } from 'near-api-js/lib/utils/key_pair';
 
 const RPC_URL = 'https://rpc.mainnet.near.org';
 
-/** Encode a UTF-8 string to a base64 string (NEAR-compatible) */
+/** Encode a UTF-8 string to a Base64 string (NEAR-compatible). */
 export function encodeBase64(input: string): string {
   return Buffer.from(input, 'utf8').toString('base64');
 }
 
-/** Decode a base64 string back to UTF-8 */
+/** Decode a Base64 string back to a UTF-8 string. */
 export function decodeBase64(input: string): string {
   return Buffer.from(input, 'base64').toString('utf8');
 }
 
-/** Encode an object to a borsh-compatible JSON Buffer for NEAR contract args */
-export function encodeArgs(args: Record<string, unknown>): Buffer {
-  return Buffer.from(JSON.stringify(args), 'utf8');
+/** Encode a plain object to a JSON-then-Base64 string suitable for NEAR function-call args. */
+export function encodeArgs(args: Record<string, unknown>): string {
+  return encodeBase64(JSON.stringify(args));
 }
 
-/** Decode a base64-encoded NEAR contract result to a typed object */
-export function decodeResult<T = unknown>(base64Result: string): T {
-  const json = Buffer.from(base64Result, 'base64').toString('utf8');
-  return JSON.parse(json) as T;
-}
-
-export interface ViewCallOptions {
-  contractId: string;
-  methodName: string;
-  args?: Record<string, unknown>;
+/** Decode a Base64 function-call args string back to a plain object. */
+export function decodeArgs(encoded: string): Record<string, unknown> {
+  return JSON.parse(decodeBase64(encoded)) as Record<string, unknown>;
 }
 
 export interface ViewCallResult<T = unknown> {
   result: T;
-  raw: string;
+  blockHash: string;
 }
 
-/** Call a NEAR view function and return decoded result via RPC */
+/**
+ * Call a NEAR view function and return the decoded result.
+ * @param contractId  The NEAR account ID of the contract.
+ * @param methodName  The view method to call.
+ * @param args        Arguments to pass (will be Base64-encoded automatically).
+ */
 export async function viewCall<T = unknown>(
-  options: ViewCallOptions
+  contractId: string,
+  methodName: string,
+  args: Record<string, unknown> = {}
 ): Promise<ViewCallResult<T>> {
-  const { contractId, methodName, args = {} } = options;
-  const argsBase64 = encodeBase64(JSON.stringify(args));
+  const encodedArgs = encodeArgs(args);
+
+  const body = {
+    jsonrpc: '2.0',
+    id: 'near-encoding',
+    method: 'query',
+    params: {
+      request_type: 'call_function',
+      finality: 'final',
+      account_id: contractId,
+      method_name: methodName,
+      args_base64: encodedArgs,
+    },
+  };
 
   const response = await fetch(RPC_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      jsonrpc: '2.0',
-      id: 'near-encoding',
-      method: 'query',
-      params: {
-        request_type: 'call_function',
-        finality: 'final',
-        account_id: contractId,
-        method_name: methodName,
-        args_base64: argsBase64,
-      },
-    }),
+    body: JSON.stringify(body),
   });
 
   if (!response.ok) {
     throw new Error(`RPC HTTP error: ${response.status}`);
   }
 
-  const json = await response.json();
+  const json = (await response.json()) as {
+    result?: { result: number[]; block_hash: string };
+    error?: { message: string };
+  };
 
-  if (json.error) {
-    throw new Error(`RPC error: ${JSON.stringify(json.error)}`);
-  }
+  if (json.error) throw new Error(`RPC error: ${json.error.message}`);
+  if (!json.result) throw new Error('Empty RPC result');
 
-  const raw: string = Buffer.from(
-    json.result.result as number[],
-    'binary' as BufferEncoding
-  )
-    .toString('base64');
+  const raw = Buffer.from(json.result.result).toString('utf8');
+  const decoded = JSON.parse(raw) as T;
 
-  const decoded = decodeResult<T>(raw);
-  return { result: decoded, raw };
+  return { result: decoded, blockHash: json.result.block_hash };
+}
+
+export interface KeyPairResult {
+  publicKey: string;
+  secretKey: string;
+  keyPair: KeyPair;
+}
+
+/** Generate a new random Ed25519 key pair for use with NEAR. */
+export function generateKeyPair(): KeyPairResult {
+  const keyPair = KeyPairEd25519.fromRandom();
+  return {
+    publicKey: keyPair.getPublicKey().toString(),
+    secretKey: keyPair.toString(),
+    keyPair,
+  };
 }
 
 export interface FunctionCallOptions {
   accountId: string;
   contractId: string;
   methodName: string;
-  args?: Record<string, unknown>;
+  args: Record<string, unknown>;
   gas?: string;
   attachedDeposit?: string;
-  keyPair?: nearApiJs.KeyPair;
+  keyPair?: KeyPair;
   networkId?: string;
 }
 
-/** Execute a NEAR state-changing function call using near-api-js Account */
+export interface FunctionCallResult {
+  transactionHash: string;
+  status: unknown;
+}
+
+/**
+ * Sign and send a NEAR function call using near-api-js.
+ * Uses the provided keyPair (from generateKeyPair) for signing.
+ */
 export async function functionCall(
   options: FunctionCallOptions
-): Promise<nearApiJs.providers.FinalExecutionOutcome> {
+): Promise<FunctionCallResult> {
   const {
     accountId,
     contractId,
     methodName,
-    args = {},
+    args,
     gas = '30000000000000',
     attachedDeposit = '0',
     keyPair,
@@ -120,27 +143,16 @@ export async function functionCall(
 
   const account = await near.account(accountId);
 
-  return account.functionCall({
+  const outcome = await account.functionCall({
     contractId,
     methodName,
-    args: encodeArgs(args),
+    args,
     gas: BigInt(gas),
     attachedDeposit: BigInt(attachedDeposit),
   });
-}
-
-export interface GeneratedKeyPair {
-  accountId: string;
-  publicKey: string;
-  keyPair: nearApiJs.KeyPair;
-}
 
-/** Generate a new ed25519 KeyPair for a given accountId (no private key param accepted) */
-export function generateKeyPair(accountId: string): GeneratedKeyPair {
-  const keyPair = KeyPairEd25519.fromRandom();
   return {
-    accountId,
-    publicKey: keyPair.getPublicKey().toString(),
-    keyPair,
+    transactionHash: outcome.transaction.hash,
+    status: outcome.status,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-encoding",
-  "version": "1.1.7619",
+  "version": "1.1.9071",
   "description": "npm Package - near-encoding",
   "main": "index.js",
   "scripts": {