Saltearse al contenido
Documentación de Aptos

Ejecutar una Red Local via CLI de Aptos

Las redes locales pueden ser útiles al probar tu código. No están conectadas a ninguna red de producción de Aptos como mainnet, pero son útiles por tres razones principales:

  1. Sin límites de tasa: Puedes interactuar con servicios alojados como Node API, Indexer API y faucet sin límites de tasa para acelerar las pruebas.
  2. Reproducibilidad: Puedes configurar escenarios específicos en cadena y reiniciar la red desde cero en cualquier momento para volver a un estado limpio.
  3. Alta disponibilidad: Las redes devnet y testnet de Aptos se actualizan periódicamente, durante lo cual pueden no estar disponibles. Las redes de desarrollo locales también están siempre disponibles incluso si no tienes acceso a internet.

Iniciar una Red Local

Sección titulada «Iniciar una Red Local»

  1. Asegúrate de tener el CLI de Aptos instalado.

  2. Asegúrate de tener Docker instalado.

    1. Esto es exclusivamente necesario para crear un entorno similar a producción ejecutando la API del Indexer. Muchas herramientas posteriores como el SDK de Aptos dependen de la API del Indexer.
    2. Docker recomienda que instales a través de Docker Desktop para obtener actualizaciones automáticas.

  3. Inicia Docker.

  4. Ejecuta el siguiente comando en una nueva terminal para iniciar la red privada:

    Ventana de terminal
    aptos node run-local-testnet --with-indexer-api

    Deberías esperar ver una salida similar a esta:

    Ventana de terminal
    Readiness endpoint: http://0.0.0.0:8070/
    

    Indexer API is starting, please wait...
    Node API is starting, please wait...
    Transaction stream is starting, please wait...
    Postgres is starting, please wait...
    Faucet is starting, please wait...
    

    Completed generating configuration:
            Log file: "/Users/dport/.aptos/testnet/validator.log"
            Test dir: "/Users/dport/.aptos/testnet"
            Aptos root key path: "/Users/dport/.aptos/testnet/mint.key"
            Waypoint: 0:397412c0f96b10fa3daa24bfda962671c3c3ae484e2d67ed60534750e2311f3d
            ChainId: 4
            REST API endpoint: http://0.0.0.0:8080
            Metrics endpoint: http://0.0.0.0:9101/metrics
            Aptosnet fullnode network endpoint: /ip4/0.0.0.0/tcp/6181
            Indexer gRPC node stream endpoint: 0.0.0.0:50051
    

    Aptos is running, press ctrl-c to exit
    

    Node API is ready. Endpoint: http://0.0.0.0:8080/
    Postgres is ready. Endpoint: postgres://postgres@127.0.0.1:5433/local_testnet
    Transaction stream is ready. Endpoint: http://0.0.0.0:50051/
    Indexer API is ready. Endpoint: http://127.0.0.1:8090
    Faucet is ready. Endpoint: http://127.0.0.1:8081/
    

    Applying post startup steps...
    

    Setup is complete, you can now use the local testnet!

  5. Espera a que la red se inicie

    Una vez que la terminal diga Setup is complete, you can now use the local testnet! la red local estará ejecutándose.

    Errores Comunes al Iniciar la Red

    Dirección Ya en Uso

    Sección titulada «Dirección Ya en Uso»
    Ventana de terminal
    panicked at 'error binding to 0.0.0.0:8080: error creating server listener: Address already in use (os error 48)'

    Esto significa que uno de los puertos necesarios por la red local ya está siendo usado por otro proceso.

    Para arreglar esto en sistemas Unix, puedes:

    1. Identificar el nombre y PID del proceso ejecutando lsof -i :8080.
    2. Ejecutar kill <pid> una vez que conozcas el PID para liberar ese puerto.

    Error de demasiados archivos abiertos

    Sección titulada «Error de demasiados archivos abiertos»
    Ventana de terminal
    panicked at crates/aptos/src/node/local_testnet/logging.rs:64:10:
    called \`Result::unwrap()\` on an \`Err\` value: Os { code: 24, kind: Uncategorized, message: \"Too many open files\" }

    Esto significa que había demasiados archivos abiertos en tu sistema. En muchos sistemas Unix puedes aumentar el número máximo de archivos abiertos agregando algo como esto a tu .zshrc:

    Ventana de terminal
    ulimit -n 1048576

    Docker no está disponible

    Sección titulada «Docker no está disponible»
    Ventana de terminal
    Unexpected error: Failed to apply pre-run steps for Postgres: Docker is not available, confirm it is installed and running. On Linux you may need to use sudo

    Para depurar esto, prueba las siguientes soluciones:

    1. Asegúrate de tener docker instalado ejecutando docker --version.
    2. Asegúrate de que el daemon de Docker esté ejecutándose ejecutando docker info (si esto da error diciendo Cannot connect to the Docker daemon Docker NO está ejecutándose).
    3. Asegúrate de que el socket para conectar a Docker esté presente en tu máquina en la ubicación predeterminada. Por ejemplo, en sistemas Unix /var/run/docker.sock debería existir.
      1. Si ese archivo no existe, abre Docker Desktop y habilita Settings -> Advanced -> Allow the default Docker socket to be used.
      2. O, puedes encontrar dónde está el socket de Docker ejecutando docker context inspect | grep Host, luego enlaza simbólicamente esa ubicación a la ubicación predeterminada ejecutando sudo ln -s /Users/dport/.docker/run/docker.sock /var/run/docker.sock

    Como puedes ver en la salida de ejemplo en el paso 4, una vez que la red local está ejecutándose, tienes acceso a los siguientes servicios:

    • Node API: Esta es una API REST que se ejecuta directamente en el nodo. Habilita funcionalidad de escritura central como envío de transacciones y un conjunto limitado de funcionalidad de lectura, como leer recursos de cuenta o información de módulos Move.
    • Indexer API: Esta es una API GraphQL que proporciona acceso de lectura rico a datos indexados de blockchain. Si haces clic en la URL para la API del Indexer arriba, por defecto http://127.0.0.1:8090, abrirá la Consola Hasura, una interfaz web que te ayudará a consultar la API GraphQL del Indexer.
    • Transaction Stream Service: Este es un stream gRPC de transacciones usado por la API del Indexer y SDK. Esto solo es relevante para ti si estás desarrollando un procesador personalizado Indexer SDK.
    • Postgres: Esta es la base de datos a la que escriben los procesadores del Indexer. La API del Indexer lee de esta base de datos.
    • Faucet: Puedes usar esto para financiar cuentas en tu red local.

    Si no quieres ejecutar ninguno de estos sub-componentes de una red, hay banderas para deshabilitarlos.

    Si estás escribiendo un script y te gustaría esperar a que la red local se inicie con todos los servicios, puedes hacer una petición GET a http://127.0.0.1:8070. Al principio esto devolverá código http 503. Cuando devuelva 200 significa que todos los servicios están listos.

    Para más información sobre diferentes banderas que puedes pasar al iniciar tu red local, o configuraciones como cambiar en qué puerto ejecutan ciertos servicios, ejecuta el comando de ayuda:

    Ventana de terminal
    aptos node run-local-testnet --help

Usar la Red Local

Sección titulada «Usar la Red Local»

Ahora que la red está ejecutándose, puedes usarla como usarías cualquier otra red.

Entonces, puedes crear un perfil local así:

Ventana de terminal
aptos init --profile <nombre-de-tu-perfil> --network local

Luego puedes usar ese perfil para cualquier comando que quieras usar en el futuro. Por ejemplo, si quisieras publicar un módulo Move como el paquete hello_blockchain a tu red local podrías ejecutar:

Ventana de terminal
aptos move publish --profile <nombre-de-tu-perfil> --package-dir /opt/git/aptos-core/aptos-move/move-examples/hello_blockchain --named-addresses HelloBlockchain=local

Configurar el SDK de TypeScript

Sección titulada «Configurar el SDK de TypeScript»

Si quieres usar la red local con el SDK de TypeScript, puedes usar URLs de red local al inicializar el objeto cliente (Aptos):

import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";


const network = Network.LOCAL;
const config = new AptosConfig({ network });
const client = new Aptos(config);

Reiniciar la red local

Sección titulada «Reiniciar la red local»

A veces durante el desarrollo es útil reiniciar la red local de vuelta a su estado inicial, por ejemplo:

  • Hiciste cambios incompatibles hacia atrás a un módulo Move, y te gustaría redistribuirlo sin renombrarlo o usar una nueva cuenta.
  • Estás construyendo un procesador personalizado Indexer SDK y te gustaría indexar usando una red fresca.
  • Quieres limpiar todo el estado en cadena, ej., cuentas, objetos, etc.

Para empezar con una red local completamente nueva, usa la bandera --force-restart:

Ventana de terminal
aptos node run-local-testnet --force-restart

Entonces te preguntará si realmente quieres reiniciar la cadena, para asegurar que no elimines tu trabajo por accidente.

Ventana de terminal
Are you sure you want to delete the existing chain? [yes/no]
> yes

Si no quieres que te pregunten, incluye --assume-yes también:

Ventana de terminal
aptos node run-local-testnet --force-restart --assume-yes