Cómo integrar contratos NEAR en frontend con API JavaScript

Clase 4 de 7 • Curso de Desarrollo en Blockchain con NEAR

Resumen

Construye Dapps con confianza: integra contratos inteligentes de NEAR en tu front end con Near API.js y controla el flujo completo, desde la conexión al RPC hasta la ejecución de métodos view y call. Aprende a gestionar llaves, seguridad y el uso de testnet en flujos reales con React, Vue.js o vanilla JavaScript.

¿Cómo integrar contratos inteligentes de NEAR en front end con Near API.js?

Para consumir un contrato desde el navegador se usan tres piezas: Near API.js, la conexión al RPC y la wallet. La lógica es simple: te conectas al endpoint, autenticas con la wallet y ejecutas métodos del contrato como view (lectura) o call (escritura). En un ejemplo básico se cargó Near API.js vía CDN minimizada v0.43 y también se mostró la instalación vía npm en proyectos con package.json.

Habilidades y conceptos practicados: - Conexión a testnet y selección de RPCs. - Manejo de keystore en navegador y wallet connection. - Definición de métodos view y change (lectura/escritura). - Ejecución con viewFunction y functionCall. - Manejo de gas y depósitos cuando el método es payable. - Flujo de login con llaves de acceso limitado y uso de allowance.

¿Cómo configurar la conexión RPC y keystore?

Usa connect de Near API.js con una configuración que apunte a la red: mainnet o testnet.
Emplea un keystore en navegador: guarda llaves en el storage local del browser para sesiones de usuario.
En CLI, las credenciales se almacenan en el equipo local, por ejemplo en una carpeta de credenciales separada por redes.

Ejemplo de flujo con Near API.js en vanilla JavaScript:

import { connect, keyStores, WalletConnection } from 'near-api-js';

const keyStore = new keyStores.BrowserLocalStorageKeyStore();
const config = { /* config de testnet con RPC y urls de wallet/helper */ };
const near = await connect({ keyStore, ...config });
const wallet = new WalletConnection(near);
const account = wallet.account();

const contractId = 'dev-xxxx.testnet';

// método de lectura (view)
const hello = await account.viewFunction({
  contractId,
  methodName: 'hello_world',
  args: {}
});

// método de escritura (call)
const tx = await account.functionCall({
  contractId,
  methodName: 'write',
  args: { key: '678', value: 'Hola, Platzi' },
  gas,               // gas suficiente.
  attachedDeposit: 0 // si el método no es payable.
});

¿Cómo autenticar con wallet y ejecutar métodos?

Inicia sesión con wallet desde el front end y autoriza acceso limitado.
Tras el login, usa wallet.account() para ejecutar viewFunction (no escribe en blockchain) y functionCall (sí escribe).
Los resultados de call aparecen como transacciones en el explorador; las view no.

¿Cómo estructurar métodos view y change?

Declara métodos de lectura como view: devuelven datos sin costo de almacenamiento.
Declara métodos de escritura como change/call: cambian estado, consumen gas y pueden requerir depósito si son payable.
Ejemplo citado: hello_world (lectura) y read/write (lectura/escritura con clave y valor tipo key–pair).

¿Qué diferencia hay entre view y call, llaves y seguridad en NEAR?

La distinción es clave para evitar errores y costos innecesarios. view solo consulta estado; call modifica el contrato. En CLI, la relación es directa: near view vs near call. En front end, viewFunction vs functionCall. Además, la seguridad se apoya en tipos de llaves y en cómo se almacenan.

Puntos esenciales: - Llaves públicas/privadas: la Dapp guarda llaves públicas en el navegador; la CLI mantiene llaves privadas en tu equipo. - Acceso limitado vs completo: el flujo de login en navegador entrega por defecto una function call access key con allowance (por ejemplo, 0.25 NEAR). No permite transferencias arbitrarias ni control total. - Full access keys: se usan en entornos de desarrollo como la CLI, donde se requiere desplegar contratos o realizar operaciones avanzadas. - Sesiones del navegador: limpiar datos del navegador cierra sesiones y elimina llaves públicas almacenadas. En incógnito, las llaves se descartan al cerrar.

¿Cómo escalar, almacenar datos y trabajar con frameworks?

En NEAR, el backend es la blockchain: se guardan colecciones de datos tipo key–pair dentro del contrato. Por eso se habla de enfoque serverless en el backend: no configuras servidores para estado o lógica; el contrato vive en la red y los nodos ejecutan tus métodos. El front end, en cambio, sí se despliega en un hosting tradicional.

Para escalar lecturas y ofrecer consultas rápidas: - Usa indexadores: servicios que cachean e indexan eventos y estado para consultas ágiles vía GraphQL o API REST. - Considera opciones descentralizadas como The Graph para evitar servidores centralizados. - Almacena archivos pesados en IPFS: se guarda un hash que referencia la imagen o video, no el binario completo on-chain.

Trabajo con frameworks y tooling: - vanilla JavaScript: ejemplo con Near API.js vía CDN y funciones asíncronas para viewFunction y functionCall. - React/Vue.js: plantillas con npx create-near-app y bandera de frontend; integración modular de wallet, contrato y vistas. - NPM/Yarn: instala near-api-js y gestiona dependencias desde package.json. - Buenas prácticas: separar conexión (RPC + keystore), autenticación (wallet) y capa de contrato (métodos view/change).