near-encoding 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# near-encoding
+
+A utility package for encoding, decoding, and interacting with NEAR smart contracts.
+
+## Installation
+
+npm install near-encoding
+
+## API & Usage
+
+### `encodeBase64(input: string): string`
+
+Encodes a UTF-8 string to Base64.
+
+import { encodeBase64 } from 'near-encoding';
+
+const encoded = encodeBase64('hello world');
+
+### `decodeBase64(input: string): string`
+
+Decodes a Base64 string back to UTF-8.
+
+import { decodeBase64 } from 'near-encoding';
+
+const decoded = decodeBase64('aGVsbG8gd29ybGQ=');
+
+### `encodeArgs(args: Record<string, unknown>): string`
+
+Encodes a plain object as a Base64 string (JSON serialized).
+
+import { encodeArgs } from 'near-encoding';
+
+const encoded = encodeArgs({ key: 'value', amount: 100 });
+
+### `functionCall(options: FunctionCallOptions): Promise<nearApiJs.providers.FinalExecutionOutcome>`
+
+Executes a NEAR smart contract function call.
+
+import { functionCall } from 'near-encoding';
+
+const outcome = await functionCall({
+  signerId: 'alice.near',
+  contractId: 'contract.near',
+  methodName: 'transfer',
+  args: { receiver_id: 'bob.near', amount: '1000' },
+});
+
+### `generateKeyPair(): GeneratedKeyPair`
+
+Generates a new NEAR key pair.
+
+import { generateKeyPair } from 'near-encoding';
+
+const keyPair = generateKeyPair();
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,157 @@
+import * as nearApiJs from 'near-api-js';
+import { KeyPair, 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) */
+export function encodeBase64(input: string): string {
+  return Buffer.from(input, 'utf8').toString('base64');
+}
+
+/** Decode a base64 string back to a UTF-8 string */
+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));
+}
+
+/** 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;
+}
+
+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;
+}
+
+/**
+ * Call a NEAR view function via RPC and return both the decoded result and its
+ * raw base64-encoded form.
+ */
+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 response = await fetch(RPC_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    throw new Error(`RPC HTTP error: ${response.status}`);
+  }
+
+  const json = (await response.json()) as {
+    result?: { result: number[] };
+    error?: { message: string };
+  };
+
+  if (json.error) {
+    throw new Error(`RPC error: ${json.error.message}`);
+  }
+
+  const raw = json.result!.result;
+  const encoded = Buffer.from(raw).toString('base64');
+  const decoded = JSON.parse(Buffer.from(raw).toString('utf8')) as T;
+
+  return { result: decoded, encoded };
+}
+
+export interface FunctionCallOptions {
+  /** NEAR account id that signs the transaction */
+  signerId: string;
+  /** NEAR account id of the contract */
+  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;
+}
+
+/**
+ * Execute a NEAR smart-contract function call, encoding args automatically.
+ * Returns the transaction outcome from the RPC.
+ */
+export async function functionCall(
+  options: FunctionCallOptions
+): Promise<nearApiJs.providers.FinalExecutionOutcome> {
+  const {
+    signerId,
+    contractId,
+    methodName,
+    args = {},
+    attachedDeposit = '0',
+    gas = '30000000000000',
+    keyPair,
+  } = options;
+
+  const keyStore = new nearApiJs.keyStores.InMemoryKeyStore();
+  await keyStore.setKey('mainnet', signerId, keyPair);
+
+  const near = await nearApiJs.connect({
+    networkId: 'mainnet',
+    nodeUrl: RPC_URL,
+    keyStore,
+  });
+
+  const account = await near.account(signerId);
+
+  const outcome = await account.functionCall({
+    contractId,
+    methodName,
+    args,
+    attachedDeposit: BigInt(attachedDeposit),
+    gas: BigInt(gas),
+  });
+
+  return outcome;
+}
+
+export interface GeneratedKeyPair {
+  publicKey: string;
+  keyPair: KeyPair;
+}
+
+/** Generate a new random Ed25519 keypair for use with NEAR accounts */
+export function generateKeyPair(): GeneratedKeyPair {
+  const keyPair = KeyPairEd25519.fromRandom();
+  return {
+    publicKey: keyPair.getPublicKey().toString(),
+    keyPair,
+  };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "near-encoding",
+  "version": "1.0.0",
+  "description": "npm Package - near-encoding",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest --passWithNoTests"
+  },
+  "keywords": [
+    "near",
+    "blockchain",
+    "web3"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "near-api-js": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ]
+}