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.
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
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:
- Desplegar en Kubernetes usando Helm
- 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 Nodo | CPU | RAM | Disco | AWS SKU | Google Cloud SKU |
---|---|---|---|---|---|
Stellar RPC | 2 vCPU | 4-8 GB | 30 GB de volumen persistente >= 3K IOPS | c5.large | n4-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:
-
Instala la herramienta CLI de Helm (versión mínima 3)
-
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
- 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 almacenamientodefault
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 parafuturenet
. Puedes sobrescribir este valor por defecto y usar otros archivosvalues.yaml
"almacenados" que han sido publicados para otras redes. Por ejemplo, hay un archivovalues-testnet.yaml
para configurar el despliegue del servidor RPC con la redtestnet
. Incluye este parámetro--values
en tuhelm 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 bajosorobanRpc.sorobanRpcConfig
ysorobanRpc.coreConfig
. Esto es aplicable al conectarse a redes específicas distintas a los archivos existentes como elvalues.yaml
disponible, como tu propia red independiente. Incluye elvalues.yaml
local enhelm 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 de2.5Gi
de memoria y1
CPU. De lo contrario, incluye los límites explícitamente en el comandohelm install
a través de los parámetrossorobanRpc.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.
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:
- Tira la imagen en la versión que te gustaría ejecutar desde las etiquetas:
docker pull stellar/stellar-rpc
- 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}"
- 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
- 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.
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:
- Accede al endpoint de estado de salud del servicio JSON RPC usando un cliente HTTP
- 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/Inteldocker.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 codificadaStrKey
de la cuenta - Establece
--TargetNetworkTestAccountSecret
al secreto codificadoStrKey
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 10msoroban_rpc_events_count
- conteo de eventos ingeridos con una ventana deslizante de 10msoroban_rpc_ingest_local_latest_ledger
- último ledger ingeridosoroban_rpc_db_round_trip_time_seconds
- tiempo requerido para ejecutar la consultaSELECT 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>