near-encoding 1.0.0 → 1.1.7619

package/README.md

@@ -1,12 +1,12 @@
 # near-encoding
 
-A utility package for encoding, decoding, and interacting with NEAR smart contracts.
+Utility functions for encoding, decoding, and interacting with the NEAR blockchain.
 
 ## Installation
 
 npm install near-encoding
 
-## API & Usage
+## API
 
 ### `encodeBase64(input: string): string`
 
@@ -16,6 +16,8 @@ import { encodeBase64 } from 'near-encoding';
 
 const encoded = encodeBase64('hello world');
 
+---
+
 ### `decodeBase64(input: string): string`
 
 Decodes a Base64 string back to UTF-8.
@@ -24,34 +26,40 @@ import { decodeBase64 } from 'near-encoding';
 
 const decoded = decodeBase64('aGVsbG8gd29ybGQ=');
 
-### `encodeArgs(args: Record<string, unknown>): string`
+---
+
+### `encodeArgs(args: Record<string, unknown>): Buffer`
 
-Encodes a plain object as a Base64 string (JSON serialized).
+Serializes a plain object into a UTF-8 encoded `Buffer` for use in NEAR contract calls.
 
 import { encodeArgs } from 'near-encoding';
 
-const encoded = encodeArgs({ key: 'value', amount: 100 });
+const buffer = encodeArgs({ token_id: '123', receiver_id: 'alice.near' });
+
+---
 
 ### `functionCall(options: FunctionCallOptions): Promise<nearApiJs.providers.FinalExecutionOutcome>`
 
-Executes a NEAR smart contract function call.
+Executes a change-method call on a NEAR contract.
 
 import { functionCall } from 'near-encoding';
 
 const outcome = await functionCall({
-  signerId: 'alice.near',
-  contractId: 'contract.near',
+  accountId: 'alice.near',
+  contractId: 'token.near',
   methodName: 'transfer',
-  args: { receiver_id: 'bob.near', amount: '1000' },
+  args: { receiver_id: 'bob.near', amount: '100' },
 });
 
-### `generateKeyPair(): GeneratedKeyPair`
+---
+
+### `generateKeyPair(accountId: string): GeneratedKeyPair`
 
-Generates a new NEAR key pair.
+Generates a new key pair associated with the given account ID.
 
 import { generateKeyPair } from 'near-encoding';
 
-const keyPair = generateKeyPair();
+const keyPair = generateKeyPair('alice.near');
 
 ## License
 

package/index.js

@@ -1,5 +1,6 @@
 import * as nearApiJs from 'near-api-js';
-import { KeyPair, KeyPairEd25519 } from 'near-api-js/lib/utils/key_pair';
+import { KeyPair } from 'near-api-js';
+import { KeyPairEd25519 } from 'near-api-js/lib/utils/key_pair';
 
 const RPC_URL = 'https://rpc.mainnet.near.org';
 
@@ -8,149 +9,137 @@ export function encodeBase64(input: string): string {
   return Buffer.from(input, 'utf8').toString('base64');
 }
 
-/** Decode a base64 string back to a UTF-8 string */
+/** Decode a base64 string back to UTF-8 */
 export function decodeBase64(input: string): string {
   return Buffer.from(input, 'base64').toString('utf8');
 }
 
-/** Encode a plain object to a JSON-then-base64 string suitable for NEAR args */
-export function encodeArgs(args: Record<string, unknown>): string {
-  return encodeBase64(JSON.stringify(args));
+/** 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');
 }
 
-/** Decode a base64-encoded NEAR args string back to a plain object */
-export function decodeArgs<T = Record<string, unknown>>(encoded: string): T {
-  return JSON.parse(decodeBase64(encoded)) as T;
+/** 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 {
-  /** NEAR account id of the contract */
   contractId: string;
-  /** Method name to call */
   methodName: string;
-  /** Arguments passed to the view method */
   args?: Record<string, unknown>;
 }
 
 export interface ViewCallResult<T = unknown> {
   result: T;
-  encoded: string;
+  raw: string;
 }
 
-/**
- * Call a NEAR view function via RPC and return both the decoded result and its
- * raw base64-encoded form.
- */
+/** Call a NEAR view function and return decoded result via RPC */
 export async function viewCall<T = unknown>(
   options: ViewCallOptions
 ): Promise<ViewCallResult<T>> {
   const { contractId, methodName, args = {} } = options;
-  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 argsBase64 = encodeBase64(JSON.stringify(args));
 
   const response = await fetch(RPC_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
+    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,
+      },
+    }),
   });
 
   if (!response.ok) {
     throw new Error(`RPC HTTP error: ${response.status}`);
   }
 
-  const json = (await response.json()) as {
-    result?: { result: number[] };
-    error?: { message: string };
-  };
+  const json = await response.json();
 
   if (json.error) {
-    throw new Error(`RPC error: ${json.error.message}`);
+    throw new Error(`RPC error: ${JSON.stringify(json.error)}`);
   }
 
-  const raw = json.result!.result;
-  const encoded = Buffer.from(raw).toString('base64');
-  const decoded = JSON.parse(Buffer.from(raw).toString('utf8')) as T;
+  const raw: string = Buffer.from(
+    json.result.result as number[],
+    'binary' as BufferEncoding
+  )
+    .toString('base64');
 
-  return { result: decoded, encoded };
+  const decoded = decodeResult<T>(raw);
+  return { result: decoded, raw };
 }
 
 export interface FunctionCallOptions {
-  /** NEAR account id that signs the transaction */
-  signerId: string;
-  /** NEAR account id of the contract */
+  accountId: string;
   contractId: string;
-  /** Method name to call */
   methodName: string;
-  /** Arguments to pass to the contract method */
   args?: Record<string, unknown>;
-  /** Amount of NEAR to attach in yoctoNEAR */
-  attachedDeposit?: string;
-  /** Gas to attach (default: 30 Tgas) */
   gas?: string;
-  /** KeyPair used to sign the transaction */
-  keyPair: KeyPair;
+  attachedDeposit?: string;
+  keyPair?: nearApiJs.KeyPair;
+  networkId?: string;
 }
 
-/**
- * Execute a NEAR smart-contract function call, encoding args automatically.
- * Returns the transaction outcome from the RPC.
- */
+/** Execute a NEAR state-changing function call using near-api-js Account */
 export async function functionCall(
   options: FunctionCallOptions
 ): Promise<nearApiJs.providers.FinalExecutionOutcome> {
   const {
-    signerId,
+    accountId,
     contractId,
     methodName,
     args = {},
-    attachedDeposit = '0',
     gas = '30000000000000',
+    attachedDeposit = '0',
     keyPair,
+    networkId = 'mainnet',
   } = options;
 
   const keyStore = new nearApiJs.keyStores.InMemoryKeyStore();
-  await keyStore.setKey('mainnet', signerId, keyPair);
+
+  if (keyPair) {
+    await keyStore.setKey(networkId, accountId, keyPair);
+  }
 
   const near = await nearApiJs.connect({
-    networkId: 'mainnet',
-    nodeUrl: RPC_URL,
+    networkId,
     keyStore,
+    nodeUrl: RPC_URL,
   });
 
-  const account = await near.account(signerId);
+  const account = await near.account(accountId);
 
-  const outcome = await account.functionCall({
+  return account.functionCall({
     contractId,
     methodName,
-    args,
-    attachedDeposit: BigInt(attachedDeposit),
+    args: encodeArgs(args),
     gas: BigInt(gas),
+    attachedDeposit: BigInt(attachedDeposit),
   });
-
-  return outcome;
 }
 
 export interface GeneratedKeyPair {
+  accountId: string;
   publicKey: string;
-  keyPair: KeyPair;
+  keyPair: nearApiJs.KeyPair;
 }
 
-/** Generate a new random Ed25519 keypair for use with NEAR accounts */
-export function generateKeyPair(): GeneratedKeyPair {
+/** 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,
   };

package/package.json

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