Saltar al contenido principal

Guía del Administrador

El servicio RPC te permite comunicarte directamente con Soroban a través de una interfaz JSON RPC.

Por ejemplo, puedes desarrollar una aplicación y hacer que envíe una transacción, obtenga el ledger y datos de eventos, o simule transacciones.

Alternativamente, puedes usar uno de los SDKs cliente de Soroban, como el @stellar/stellar-sdk, que necesitará comunicarse con una instancia de RPC para acceder a la red.

Ejecutar tu propia instancia para desarrollo

Para desarrollo local, recomendamos descargar y ejecutar una instancia local a través de Docker Quickstart y ejecutar una red local o comunicarte con un Testnet en vivo.

advertencia

No recomendamos ejecutar la imagen Quickstart en producción. Consulta la sección de desplegar tu propia instancia de RPC.

La imagen de inicio rápido con el servicio RPC puede ejecutarse en una laptop estándar con 8 GB de RAM y tiene requisitos mínimos de almacenamiento y CPU. Es un solo contenedor que ejecuta todo lo que necesitas para probar contra una red con todas las funciones. Contiene:

  • Stellar Core - Software de nodo que ejecuta la red, coordina el consenso y finaliza los ledgers.
  • Servidor Stellar RPC - Servidor JSON RPC para interactuar con contratos Soroban.
  • Servidor Horizon - API HTTP para acceder al estado del ledger y a transacciones históricas.
  • Servidor Friendbot - API HTTP para crear y financiar nuevas cuentas en redes de prueba.

Independiente

Para ejecutar una red independiente local con la imagen de Docker de Stellar Quickstart, ejecuta el siguiente comando:

docker run --rm -it \
-p 8000:8000 \
--name stellar \
stellar/quickstart:testing \
--local \
--enable-soroban-rpc

Una vez que la imagen esté iniciada, puedes verificar su estado consultando la API de Horizon:

curl "http://localhost:8000"

Puedes interactuar con este nodo local usando el CLI de Stellar. Primero, agrégalo como una red configurada:

stellar network add local \
--rpc-url "http://localhost:8000/soroban/rpc" \
--network-passphrase "Standalone Network ; February 2017"

Luego genera una identidad única (keypair pública/privada) y júntala usando:

stellar keys generate alice
Identidades solo para pruebas

Es una buena práctica nunca usar las mismas llaves para pruebas y desarrollo que uses para la red pública de Stellar. Genera nuevas llaves para pruebas y desarrollo y evita usarlas para otros propósitos.

Ahora que tienes una red configurada y una identidad financiada, puedes usar estas en otros comandos de CLI de Stellar. Por ejemplo, desplegar un contrato:

stellar contract deploy \
--wasm target/wasm32-unknown-unknown/release/[project_name].wasm \
--source alice \
--network local

O invocar un contrato:

stellar contract invoke \
--id C... \
--source alice \
--network local \
-- \
hello \
--to friend

Cuando hayas terminado con tu nodo local, puedes cerrarlo con ctrlc (no cmd). Esto eliminará completamente el contenedor (eso es lo que hace la opción --rm del comando docker), lo que significa que necesitarás volver a desplegar tu contrato y volver a financiar tu identidad la próxima vez que lo inicies. Si trabajas con nodos locales a menudo, tal vez quieras crear scripts para facilitar estos pasos de inicialización. Por ejemplo, consulta el initialize.sh de la dapp de ejemplo.

Testnet

Ejecutar tu propio nodo Testnet funciona de la misma manera que ejecutar un nodo Quickstart, como se describió anteriormente. Necesitarás modificaciones menores para algunos comandos. Primero necesitas --testnet para la instancia de docker, en lugar de --standalone:

docker run --rm -it \
-p 8000:8000 \
--name stellar \
stellar/quickstart:testing \
--testnet \
--enable-soroban-rpc

Y querrás configurarlo para su uso con el flag --network en Stellar CLI:

stellar network add testnet \
--rpc-url "http://localhost:8000/soroban/rpc" \
--network-passphrase "Test SDF Network ; September 2015"

Reemplaza testnet en ese comando con el nombre de tu elección si deseas dejar el nombre testnet disponible para su uso con un proveedor de RPC público (consulta más abajo). O haz un uso inteligente de las configuraciones --global para proveedores públicos y configuraciones locales (hechas con el comando network add no decorado anterior) para nodos locales.

Ahora puedes reemplazar --network standalone con --network testnet (o como lo hayas nombrado) en todos tus comandos que necesiten una red, como los comandos deploy e invoke mencionados anteriormente.

Futurenet

También puedes desarrollar tus contratos Soroban contra la red Futurenet. Puedes elegir esto si deseas probar características más avanzadas que aún no han llegado al Testnet. Ejecutar tu propio nodo Futurenet funciona igual que ejecutar un nodo Testnet, como se describió anteriormente.

docker run --rm -it \
-p 8000:8000 \
--name stellar \
stellar/quickstart:future \
--futurenet \
--enable-soroban-rpc

Y querrás configurarlo para su uso con el flag --network en Stellar CLI:

stellar network add futurenet \
--rpc-url "http://localhost:8000/soroban/rpc" \
--network-passphrase "Test SDF Future Network ; October 2022"

Reemplaza futurenet en ese comando con el nombre de tu elección, si quieres dejar el nombre futurenet disponible para su uso con un proveedor de RPC público (consulta más abajo). O haz un uso inteligente de las configuraciones --global para proveedores públicos y configuraciones locales (hechas con el comando network add no decorado anterior) para nodos locales.

Ahora puedes reemplazar --network standalone con --network futurenet (o como lo hayas nombrado) en todos tus comandos que necesiten una red, como los comandos deploy e invoke mencionados anteriormente.

Desplegar tu propia instancia de RPC

Recomendamos las siguientes formas de desplegar tu propia instancia de RPC:

  1. Desplegar en Kubernetes usando Helm
  2. Ejecutar directamente la imagen docker stellar-rpc

Requisitos de Hardware

Para implementaciones que esperan hasta 1000 solicitudes por segundo al Stellar RPC, recomendamos al menos 4 GB de RAM y al menos un CPU de doble núcleo con una velocidad de reloj de 2.4 GHz.

Para implementaciones que esperan entre 1000 y 10000+ solicitudes por segundo al Stellar RPC, recomendamos al menos 8 GB de RAM y al menos un CPU de cuatro núcleos con una velocidad de reloj de 2.4 GHz.

Para todas las implementaciones, recomendamos al menos 10 GB de espacio en disco/almacenamiento.

Tipo de NodoCPURAMDiscoAWS SKUGoogle Cloud SKU
Stellar RPC2 vCPU4-8 GB30 GB de volumen persistente >= 3K IOPSc5.largen4-highcpu-2

* Suponiendo una ventana de retención de 7 días para el almacenamiento de datos.

Kubernetes Con Helm

Si tu entorno de implementación incluye infraestructura de Kubernetes, esta es la forma preferida de desplegar tu instancia de RPC. Aquí tienes lo que necesitas hacer:

  1. Instala la herramienta CLI de Helm (versión mínima 3)

  2. Agrega el repositorio de Stellar a la lista de repos de la cli de helm, actualízalo a las versiones publicadas más recientes

helm repo add stellar https://helm.stellar.org/charts
helm repo update stellar
  1. Despliega la instancia de RPC en Kubernetes usando nuestro gráfico de Helm:
helm install my-rpc stellar/stellar-rpc \
--namespace my-rpc-namespace-on-cluster \
--set global.image.sorobanRpc.tag=22.1.1 \
--set sorobanRpc.ingress.host=myrpc.example.org \
--set sorobanRpc.persistence.enabled=true \
--set sorobanRpc.persistence.storageClass=default \
--set sorobanRpc.resources.limits.cpu=1 \
--set sorobanRpc.resources.limits.memory=2560Mi

Este ejemplo de uso de gráfico de Helm destaca algunos aspectos clave:

  • Establece global.image.sorobanRpc.tag a una etiqueta del repositorio stellar-rpc dockerhub para la versión de imagen que deseas ejecutar. Consulta la página de versiones de software para encontrar la etiqueta correcta para la versión de Soroban que estás ejecutando.

  • El servidor RPC almacena una ventana rotativa de datos recientes de los ledgers de la red en disco. El tamaño de esos datos varía dependiendo de la red y sus volúmenes de transacciones, pero tiene un rango estimado de entre 10 a 100 MB. Para asegurar que el pod RPC tenga acceso constante al espacio de almacenamiento en disco y a un rendimiento de lectura/escritura, este ejemplo demuestra cómo habilitar opcionalmente el despliegue del gráfico de Helm para usar un PersistentVolumeClaim (PVC) de 100MB de la clase de almacenamiento default en Kubernetes habilitando estos parámetros de persistencia:

--set sorobanRpc.persistence.enabled=true
--set sorobanRpc.persistence.storageClass=default

Por defecto, esto está deshabilitado (sorobanRpc.persistence.enabled=false) y el despliegue RPC usará almacenamiento efímero de pod a través de emptyDir, lo cual probablemente sea adecuado para los volúmenes de transacciones de futurenet y testnet. Sin embargo, vale la pena resaltar la compensación de no tener restricciones de almacenamiento del clúster impuestas (probablemente por debajo de 100 MB).

  • Los preajustes de red están definidos en values.yaml, que actualmente establece una configuración de red específica para futurenet. Puedes sobrescribir este valor por defecto y usar otros archivos values.yaml "almacenados" que han sido publicados para otras redes. Por ejemplo, hay un archivo values-testnet.yaml para configurar el despliegue del servidor RPC con la red testnet. Incluye este parámetro --values en tu helm install para especificar la red deseada:
--values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/soroban-rpc/values-testnet.yaml
  • Configurar RPC para usar otras redes personalizadas se puede lograr descargando el values.yaml localmente y actualizando los ajustes bajo sorobanRpc.sorobanRpcConfig y sorobanRpc.coreConfig. Esto es aplicable al conectarse a redes específicas distintas a los archivos existentes como el values.yaml disponible, como tu propia red independiente. Incluye el values.yaml local en helm install:
--values my-custom-values.yaml
  • Verifica los valores por defecto de LimitRange en el namespace de destino en Kubernetes para el despliegue. LimitRange es opcional en la configuración del clúster. Si se define, asegúrate de que los valores predeterminados proporcionen al menos límites mínimos de recursos para el servidor RPC de 2.5Gi de memoria y 1 CPU. De lo contrario, incluye los límites explícitamente en el comando helm install a través de los parámetros sorobanRpc.resources.limits.*:
--set sorobanRpc.resources.limits.cpu=1
--set sorobanRpc.resources.limits.memory=2560Mi

Incluso si no estás desplegando Stellar RPC usando Kubernetes, los manifiestos generados por los gráficos pueden seguir siendo una buena referencia para mostrar cómo configurar y ejecutar Stellar RPC como un contenedor de docker. Simplemente ejecuta el comando helm template para imprimir la configuración del contenedor en la pantalla:

helm template my-rpc stellar/stellar-rpc

Imagen de Docker

Si usar Kubernetes no es una opción, esta es la forma preferida de desplegar tu propia instancia de RPC.

advertencia

Aunque tenemos una Imagen Quickstart, es solo para desarrollo y pruebas locales. No es adecuada para despliegues de producción.

Aquí tienes cómo ejecutar la imagen docker stellar-rpc:

  1. Tira la imagen en la versión que te gustaría ejecutar desde las etiquetas:
docker pull stellar/stellar-rpc
  1. Crea un archivo de configuración para Stellar Core. Aquí tienes un ejemplo de archivo de configuración para Testnet:
HTTP_PORT=11626
PUBLIC_HTTP_PORT=false

NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

DATABASE="sqlite3://stellar.db"

# Stellar Testnet Validators
[[HOME_DOMAINS]]
HOME_DOMAIN="testnet.stellar.org"
QUALITY="HIGH"

[[VALIDATORS]]
NAME="sdftest1"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y"
ADDRESS="core-testnet1.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_001/{0} -o {1}"

[[VALIDATORS]]
NAME="sdftest2"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP"
ADDRESS="core-testnet2.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_002/{0} -o {1}"

[[VALIDATORS]]
NAME="sdftest3"
HOME_DOMAIN="testnet.stellar.org"
PUBLIC_KEY="GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z"
ADDRESS="core-testnet3.stellar.org"
HISTORY="curl -sf http://history.stellar.org/prd/core-testnet/core_testnet_003/{0} -o {1}"
  1. Crea y monta un volumen monta un volumen en tu contenedor donde se almacena la configuración anterior. Un ejemplo para Testnet:

Si estás ejecutando localmente en un macOS por ejemplo, podrías crear una carpeta en tu directorio home: ~/test-rpc-config

cd ~
mkdir test-rpc-config

Luego agregarías los siguientes archivos de configuración a ese directorio local:

  • soroban-rpc-config.toml
  • stellar-captive-core.cfg

Luego montarías ese volumen añadiendo el siguiente parámetro: -v /Users/<USERNAME>/test-rpc-config:/opt/stellar a tu comando docker run.

Tu contenedor en ejecución montaría ese volumen en la ruta /opt/stellar

  1. Ejecuta la imagen

En ese ejemplo, podrías ejecutar el contenedor stellar/stellar-rpc con el siguiente comando:

docker run -p 8001:8001 -p 8000:8000 \
-v /Users/<USERNAME>/test-rpc-config:/opt/stellar stellar/stellar-rpc \
--captive-core-config-path=/opt/stellar/stellar-captive-core.cfg \
--captive-core-storage-path="/var/lib/stellar/captive-core" \
--db-path="/var/lib/stellar/soroban-rpc-db.sqlite" \
--stellar-captive-core-http-port=11626 \
--friendbot-url="https://friendbot-testnet.stellar.org/" \
--network-passphrase="Test SDF Network ; September 2015" \
--history-archive-urls="https://history.stellar.org/prd/core-testnet/core_testnet_001" \
--admin-endpoint="0.0.0.0:8001" \
--endpoint="0.0.0.0:8000"

Configuración

Para producción, recomendamos ejecutar Stellar RPC con un archivo de configuración TOML en lugar de flags de CLI. Esto es similar a crear un archivo de configuración para Stellar-Core como hicimos anteriormente. Por ejemplo, usando nuestra imagen de Docker:

docker run -p 8001:8001 -p 8000:8000 \
-v <CONFIG_FOLDER>:/config stellar/stellar-rpc \
--config-path <RPC_CONFIG_FILENAME>

Puedes usar este subcomando Stellar RPC para generar un archivo de configuración inicial:

docker run stellar/stellar-rpc:latest gen-config-file > soroban-rpc-config.toml

La configuración resultante debería lucir así:

# Admin endpoint to listen and serve on. WARNING: this should not be accessible
# from the Internet and does not use TLS. "" (default) disables the admin server
# ADMIN_ENDPOINT = ""

# path to additional configuration for the Stellar Core configuration file used
# by captive core. It must, at least, include enough details to define a quorum
# set
# CAPTIVE_CORE_CONFIG_PATH = ""

# Storage location for Captive Core bucket data
CAPTIVE_CORE_STORAGE_PATH = "/"

# establishes how many ledgers exist between checkpoints, do NOT change this
# unless you really know what you are doing
CHECKPOINT_FREQUENCY = 64

# configures classic fee stats retention window expressed in number of ledgers
CLASSIC_FEE_STATS_RETENTION_WINDOW = 10

# SQLite DB path
DB_PATH = "soroban_rpc.sqlite"

# Default cap on the amount of events included in a single getEvents response
DEFAULT_EVENTS_LIMIT = 100

# Default cap on the amount of ledgers included in a single getLedgers response
DEFAULT_LEDGERS_LIMIT = 50

# Default cap on the amount of transactions included in a single getTransactions
# response
DEFAULT_TRANSACTIONS_LIMIT = 50

# Endpoint to listen and serve on
ENDPOINT = "localhost:8000"

# The friendbot URL to be returned by getNetwork endpoint
# FRIENDBOT_URL = ""

# comma-separated list of stellar history archives to connect with
HISTORY_ARCHIVE_URLS = []

# configures history retention window for transactions and events, expressed in
# number of ledgers, the default value is 120960 which corresponds to about 7
# days of history
HISTORY_RETENTION_WINDOW = 120960

# Ingestion Timeout when bootstrapping data (checkpoint and in-memory
# initialization) and preparing ledger reads
INGESTION_TIMEOUT = "50m0s"

# format used for output logs (json or text)
# LOG_FORMAT = "text"

# minimum log severity (debug, info, warn, error) to log
LOG_LEVEL = "info"

# Maximum amount of events allowed in a single getEvents response
MAX_EVENTS_LIMIT = 10000

# The maximum duration of time allowed for processing a getEvents request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_EVENTS_EXECUTION_DURATION = "10s"

# The maximum duration of time allowed for processing a getFeeStats request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_FEE_STATS_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getHealth request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_HEALTH_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getLatestLedger request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_LATEST_LEDGER_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getLedgers request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_LEDGERS_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getLedgerEntries
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_GET_LEDGER_ENTRIES_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getNetwork request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_NETWORK_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getTransactions request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTIONS_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTION_EXECUTION_DURATION = "5s"

# The maximum duration of time allowed for processing a getVersionInfo request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_VERSION_INFO_EXECUTION_DURATION = "5s"

# maximum ledger latency (i.e. time elapsed since the last known ledger closing
# time) considered to be healthy (used for the /health endpoint)
MAX_HEALTHY_LEDGER_LATENCY = "30s"

# Maximum amount of ledgers allowed in a single getLedgers response
MAX_LEDGERS_LIMIT = 200

# The max request execution duration is the predefined maximum duration of time
# allowed for processing a request. When that time elapses, the server would
# return 504 and abort the request's execution
MAX_REQUEST_EXECUTION_DURATION = "25s"

# The maximum duration of time allowed for processing a sendTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_SEND_TRANSACTION_EXECUTION_DURATION = "15s"

# The maximum duration of time allowed for processing a simulateTransaction
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_SIMULATE_TRANSACTION_EXECUTION_DURATION = "15s"

# Maximum amount of transactions allowed in a single getTransactions response
MAX_TRANSACTIONS_LIMIT = 200

# Network passphrase of the Stellar network transactions should be signed for.
# Commonly used values are "Test SDF Future Network ; October 2022", "Test SDF
# Network ; September 2015" and "Public Global Stellar Network ; September 2015"
# NETWORK_PASSPHRASE = ""

# Enable debug information in the simulate transaction response (provides more detailed errors). It
# should not be enabled in production deployments.
PREFLIGHT_ENABLE_DEBUG = true

# Number of workers (read goroutines) used for the
# simulateTransaction endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_COUNT = 8

# Maximum number of outstanding requests for the simulateTransaction
# endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_QUEUE_SIZE = 8

# Maximum number of outstanding GetEvents requests
REQUEST_BACKLOG_GET_EVENTS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetFeeStats requests
REQUEST_BACKLOG_GET_FEE_STATS_QUEUE_LIMIT = 100

# Maximum number of outstanding GetHealth requests
REQUEST_BACKLOG_GET_HEALTH_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetLatestsLedger requests
REQUEST_BACKLOG_GET_LATEST_LEDGER_QUEUE_LIMIT = 1000

# Maximum number of outstanding getLedgers requests
REQUEST_BACKLOG_GET_LEDGERS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetLedgerEntries requests
REQUEST_BACKLOG_GET_LEDGER_ENTRIES_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetNetwork requests
REQUEST_BACKLOG_GET_NETWORK_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetTransactions requests
REQUEST_BACKLOG_GET_TRANSACTIONS_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetTransaction requests
REQUEST_BACKLOG_GET_TRANSACTION_QUEUE_LIMIT = 1000

# Maximum number of outstanding GetVersionInfo requests
REQUEST_BACKLOG_GET_VERSION_INFO_QUEUE_LIMIT = 1000

# Maximum number of outstanding requests
REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT = 5000

# Maximum number of outstanding SendTransaction requests
REQUEST_BACKLOG_SEND_TRANSACTION_QUEUE_LIMIT = 500

# Maximum number of outstanding SimulateTransaction requests
REQUEST_BACKLOG_SIMULATE_TRANSACTION_QUEUE_LIMIT = 100

# The request execution warning threshold is the predetermined maximum duration
# of time that a request can take to be processed before a warning would be
# generated
REQUEST_EXECUTION_WARNING_THRESHOLD = "5s"

# configures soroban inclusion fee stats retention window expressed in number of
# ledgers
SOROBAN_FEE_STATS_RETENTION_WINDOW = 50

# HTTP port for Captive Core to listen on (0 disables the HTTP server)
STELLAR_CAPTIVE_CORE_HTTP_PORT = 11626

# path to stellar core binary
STELLAR_CORE_BINARY_PATH = "/usr/bin/stellar-core"

# Timeout used when submitting requests to stellar-core
STELLAR_CORE_TIMEOUT = "2s"

# URL used to query Stellar Core (local captive core by default)
# STELLAR_CORE_URL = ""

# Enable strict toml configuration file parsing. This will prevent unknown
# fields in the config toml from being parsed.
# STRICT = false

Nota que la configuración generada anterior contiene los valores por defecto y necesitas sustituirlos por valores apropiados para ejecutar la imagen.

Construir desde el Código Fuente

Instrucciones para construir Stellar RPC desde el código fuente pueden encontrarse aquí.

Usar tu Instancia RPC Local

Puedes configurar el CLI de Stellar para usar tu endpoint RPC remoto local:

stellar network add --global local \
--rpc-url http://localhost:8000 \
--network-passphrase 'Standalone Network ; February 2017'

Y financiar tus cuentas/identidades con el Friendbot:

curl "http://localhost:8000/friendbot/?addr=$(stellar keys address alice)"

Consulta el consejo anterior sobre la expansión de comandos (esa es la nota sobre $(...)) si no estás usando un shell basado en bash.

advertencia

Al interactuar con la red en producción deberías ejecutar tu propio stellar-rpc o usar un proveedor de infraestructura de terceros.

Verificar la Instancia RPC

Después de la instalación, valdrá la pena verificar que la instalación de Stellar RPC esté saludable. Hay dos métodos:

  1. Accede al endpoint de estado de salud del servicio JSON RPC usando un cliente HTTP
  2. Usa nuestra imagen Docker de Prueba del Sistema como herramienta para realizar una serie de pruebas en vivo contra Stellar RPC

Endpoint de Estado de Salud

Si envías una solicitud HTTP JSON RPC a tu instancia en ejecución de Stellar RPC:

curl --location 'http://localhost:8000' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc":"2.0",
"id":2,
"method":"getHealth"
}'

Deberías obtener de vuelta una respuesta de estado HTTP 200 si la instancia es saludable:

{
"jsonrpc": "2.0",
"id": 2,
"result": {
"status": "healthy"
}
}

Imagen de Prueba del Sistema

Esta prueba compilará, desplegará e invocará contratos de ejemplo a la red a la que tu instancia RPC está conectada. Aquí tienes un ejemplo para verificar tu instancia si está conectada a Testnet:

docker run --rm -t --name e2e_test \
docker.io/stellar/system-test:soroban-v20 \
--VerboseOutput true \
--TargetNetworkRPCURL <your rpc url here> \
--TargetNetworkPassphrase "Test SDF Network ; September 2015" \
--TargetNetworkTestAccountSecret <your test account StrKey encoded key here > \
--TargetNetworkTestAccountPublic <your test account StrKey encoded pubkey here> \
--SorobanExamplesGitHash v22.0.1

Asegúrate de configurar correctamente la prueba del sistema:

  • Usa una etiqueta de prueba del sistema publicada que se alinee con la versión del lanzamiento del Stellar RPC desplegado. Para cada lanzamiento, habrá dos etiquetas publicadas para diferentes arquitecturas de CPU. Asegúrate de usar la etiqueta que coincida con la arquitectura de CPU de tu máquina anfitriona:
    • docker.io/stellar/system-test:<nombre del lanzamiento> para máquinas con CPUs basadas en AMD/Intel
    • docker.io/stellar/system-test:<nombre del lanzamiento>-arm64 para máquinas con CPUs ARM
  • Establece --TargetNetworkRPCURL a tu URL HTTP RPC
  • Establece --TargetNetworkPassphrase a la misma red a la que está conectado tu instancia RPC:
    • "Test SDF Network ; Septiembre 2015" para Testnet
    • "Test SDF Future Network ; Octubre 2022" para Futurenet
  • Establece --SorobanExamplesGitHash a la etiqueta de versión correspondiente en el repositorio de Ejemplos de Soroban
  • Crea y financia una cuenta que se utilizará para propósitos de prueba en la misma red a la que está conectado tu instancia RPC
    • Esta cuenta necesita un pequeño balance de XLM para enviar transacciones de Soroban
    • Las pruebas se pueden ejecutar repetidamente con la misma cuenta
    • Establece --TargetNetworkTestAccountPublic a la clave pública codificada StrKey de la cuenta
    • Establece --TargetNetworkTestAccountSecret al secreto codificado StrKey para la cuenta

Monitorea la instancia RPC

Si ejecutas Stellar RPC con el --admin-endpoint configurado y exponer el puerto, tendrás acceso a las métricas de Prometheus a través del punto final /metrics. Por ejemplo, si el punto final de administración es 0.0.0.0:8001 y estás ejecutando la imagen de Docker de Stellar RPC:

curl localhost:8001/metrics

Verás muchas de las métricas predeterminadas de Go y Proceso (prefijadas por go_ y process_ respectivamente) como uso de memoria, uso de CPU, número de hilos, etc.

También exponemos métricas relacionadas con Stellar RPC (prefijadas por soroban_rpc). Hay muchas, pero algunas notables son:

  • soroban_rpc_transactions_count - conteo de transacciones ingeridas con una ventana deslizante de 10m
  • soroban_rpc_events_count - conteo de eventos ingeridos con una ventana deslizante de 10m
  • soroban_rpc_ingest_local_latest_ledger - último ledger ingerido
  • soroban_rpc_db_round_trip_time_seconds - tiempo requerido para ejecutar la consulta SELECT 1 en la BASE DE DATOS

Stellar RPC también proporciona registro en consola para:

  • Actividad de inicio
  • Ingerir, aplicar y cerrar ledgers
  • Manejo de solicitudes JSON RPC
  • Cualquier error

Los registros tienen el formato:

time=<timestamp in YYYY-MM-DDTHH:MM:SS.000Z format> level=<debug|info|error> msg=<Actual message> pid=<process ID> subservice=<optional if coming from subservice>