Arxi Decision Gate Asset Core
Docs
Documentació d'Asset Core

Documentació del motor d'estat del món determinista i referències de l'API.

Decision Gate docs

Primer compromís i lectura

Aquesta guia et guia a través de l’execució dels daemons d’Asset Core localment, enviant un compromís simple i llegint l’estat resultant. Està dissenyada per confirmar que el teu entorn està connectat correctament de principi a fi abans de modelar dominis més complexos.

Requisits previs

Assegureu-vos que podeu executar processos locals i llegir fitxers de token. Obriu dues terminals per poder observar ambdós daemons i el camí de lectura de manera independent.

  • Docker + Docker Compose (recomanat) o cadena d’eines Rust per a construccions locals
  • Client HTTP (curl) més jq per a l’extracció de tokens
  • Terminal amb dues finestres o pestanyes

Pas 1 - Iniciar els daemons (Docker Compose)

Des de la carpeta arrel d’Asset Core:

docker-compose up -d

Això inicia els daemons d’escriptura i lectura als ports 8080 i 8081 utilitzant ./data per a l’emmagatzematge. El registre de confirmacions i els fitxers de tokens es crearan sota aquest directori.

Pas 2 - Configura el namespace i els tokens

En el primer 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)

Els tokens es guarden a data/auth/tokens en el flux de treball de Docker (o ./.assetcore/auth/tokens per a binaris locals). Mantingueu aquests tokens privats i tracteu-los com a credencials de producció.

Verifica que s’estigui executant:

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

Esperat resposta:

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

Pas 3 - Verificar la salut del daemon de lectura

En el segon 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 segueix el mateix registre de commits que el daemon d’escriptura, i les comprovacions de salut requereixen un encapçalament de namespace. Aquesta és una manera senzilla de confirmar que el camí de lectura pot veure el namespace que planegeu utilitzar.

S’espera que la resposta inclogui metadades de preparació i frescor.

Pas 4 - Envia el teu primer commit

Provisioneu l’espai de noms (una vegada) i després creeu un contenidor i afegiu un saldo fungible en una sola transacció. Això reflecteix un patró realista de “crear + sembrar” sense requerir cap esquema personalitzat.

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"
  }'

Esperat resposta:

{
  "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 el teu compromís va ser assignat el número de seqüència 1. Aquest número és la seqüència pública, per-namespace que hauries d’utilitzar per a l’auditoria i la reproducció.

Pas 5 - Llegir l’estat de nou

Consulta els saldos dels contenidors:

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

Esperat resposta:

{
  "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
  }
}

La metadada freshness mostra que el daemon de lectura ha processat tots els commits a través de la seqüència 1. En producció, podeu utilitzar la frescor per detectar retards i fer complir la seqüència mínima de lectura.

Solució de problemes

”Connexió rebutjada” en el compromís

El daemon d’escriptura no s’està executant o està en un port diferent. Comproveu el terminal per errors i verifiqueu que el camí --config sigui correcte.

Saldo buit en lectura

El daemon de lectura no ha assolit el daemon d’escriptura. Comproveu que ambdós daemons utilitzin la mateixa ruta del registre de confirmacions. La metadada de frescor mostra l’última seqüència mundial aplicada.

Error “ContainerNotFound”

L’ID del contenidor en la vostra consulta de lectura no coincideix amb el que heu creat. Els IDs de contenidor són enters, no cadenes.

Error “InvalidQuantity”

La quantitat ha de ser superior a zero. Comproveu la vostra operació AddFungible.

Properes passes