Arxi Puerta de Decisión Asset Core
Docs
Documentos de Asset Core

Documentación del motor de estado mundial determinista y referencias de API.

Documentos de Decision Gate

Primer Commit y Leer

Esta guía te guía a través de la ejecución de los demonios de Asset Core localmente, enviando un compromiso simple y leyendo el estado resultante. Está diseñada para confirmar que tu entorno está correctamente conectado de extremo a extremo antes de modelar dominios más complejos.

Requisitos previos

Asegúrate de poder ejecutar procesos locales y leer archivos de tokens. Abrirás dos terminales para que puedas observar ambos demonios y la ruta de lectura de manera independiente.

  • Docker + Docker Compose (recomendado) o herramienta de Rust para compilaciones locales
  • Cliente HTTP (curl) más jq para la extracción de tokens
  • Terminal con dos ventanas o pestañas

Paso 1 - Iniciar los demonios (Docker Compose)

Desde la raíz del repositorio de Asset Core:

docker-compose up -d

Esto inicia los demonios de escritura y lectura en los puertos 8080 y 8081 utilizando ./data para almacenamiento. El registro de confirmaciones y los archivos de tokens se crearán en ese directorio.

Paso 2 - Establecer el espacio de nombres y los tokens

En la primera terminal:

export ASSETCORE_NAMESPACE_ID=5001
export ASSETCORE_ADMIN_TOKEN=$(jq -r .token data/auth/tokens/admin.json)
export ASSETCORE_WRITE_TOKEN=$(jq -r .token data/auth/tokens/writer.json)
export ASSETCORE_READ_TOKEN=$(jq -r .token data/auth/tokens/reader.json)

Los tokens se almacenan en data/auth/tokens en el flujo de trabajo de Docker (o ./.assetcore/auth/tokens para binarios locales). Mantenga estos tokens en privado y trátelos como credenciales de producción.

Verifica que esté en funcionamiento:

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://127.0.0.1:8080/v1/write/health

Respuesta esperada:

{
  "status": "healthy",
  "version": "0.1.0",
  "api_version": "0.1.0",
  "build_git_sha": "abc123",
  "uptime_secs": 3600
}

Paso 3 - Verificar la salud del daemon de lectura

En el segundo terminal:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  -H "x-assetcore-namespace: $ASSETCORE_NAMESPACE_ID" \
  http://127.0.0.1:8081/v1/read/health

El daemon de lectura sigue el mismo registro de confirmaciones que el daemon de escritura, y las comprobaciones de salud requieren un encabezado de espacio de nombres. Esta es una forma sencilla de confirmar que la ruta de lectura puede ver el espacio de nombres que planeas utilizar.

Se espera que la respuesta incluya metadatos de preparación y frescura.

Paso 4 - Envía tu primer commit

Provisione el espacio de nombres (una vez) y luego cree un contenedor y agregue un saldo fungible en una sola transacción. Esto refleja un patrón realista de “crear + sembrar” sin requerir ningún esquema personalizado.

curl -X POST http://127.0.0.1:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/lifecycle \
  -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_state":"provisioned","reason":"quickstart bootstrap"}'

curl -X POST http://127.0.0.1:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": { "type": "balance" },
          "owner": null,
          "policies": null
        }
      },
      {
        "op": "AddFungible",
        "args": {
          "class_id": 100,
          "key": 1,
          "quantity": 500,
          "location": {
            "container_id": 1001,
            "kind": "balance"
          }
        }
      }
    ],
    "idempotency_key": "first-commit-2026-01-15"
  }'

Respuesta esperada:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 1,
  "world_seq_end": 1,
  "event_count": 2,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "first-commit-2026-01-15"
  },
  "created_entities": {
    "containers": [1001]
  }
}

El world_seq_start confirma que tu compromiso fue asignado con el número de secuencia 1. Este número es la secuencia pública, por espacio de nombres, que deberías usar para la auditabilidad y la reproducción.

Paso 5 - Leer de nuevo el estado

Consulta los saldos de los contenedores:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://127.0.0.1:8081/v1/read/namespaces/${ASSETCORE_NAMESPACE_ID}/containers/1001/balances

Respuesta esperada:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "freshness": {
    "namespace": 5001,
    "world_seq": 1,
    "commit_log_world_seq": 1,
    "lag": 0,
    "lag_ms": 0
  }
}

Los metadatos de freshness muestran que el daemon de lectura ha procesado todos los commits a través de la secuencia 1. En producción, puedes utilizar freshness para detectar retrasos y hacer cumplir la secuenciación mínima de lectura.

Solución de problemas

”Conexión rechazada” al hacer commit

El daemon de escritura no está en ejecución o está en un puerto diferente. Verifique la terminal en busca de errores y confirme que la ruta --config es correcta.

Saldos vacíos en lectura

El daemon de lectura no ha alcanzado al daemon de escritura. Verifique que ambos daemons utilicen la misma ruta del registro de confirmaciones. Los metadatos de frescura muestran la última secuencia mundial aplicada.

Error “ContainerNotFound”

El ID del contenedor en su consulta de lectura no coincide con lo que creó. Los IDs de contenedor son enteros, no cadenas.

Error “InvalidQuantity”

La cantidad debe ser mayor que cero. Verifique su operación AddFungible.

Próximos pasos