Transacciones

Una transacción es una lista de operaciones que se ejecutan de manera atómica. Esta referencia describe la estructura JSON de las solicitudes de confirmación.

Visión general

Todos los cambios de estado fluyen a través del endpoint /v1/commit como transacciones. El daemon de escritura valida, ejecuta y persiste las operaciones antes de devolver una respuesta de éxito.

Estructura

Solicitud de Compromiso

{
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  }
}

Operación Sobre

Cada operación tiene la misma estructura de sobre:

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

Campos

Campos de Solicitud

Campo	Tipo	Requerido	Descripción
operations	array	Sí	Lista de operaciones a ejecutar
idempotency_key	string	No	Clave única para deduplicación
metadata	object	No	Metadatos definidos por el usuario reflejados en la respuesta

Campos del Sobre de Operación

Campo	Tipo	Requerido	Descripción
op	cadena	Sí	Identificador de operación
args	objeto	Sí	Argumentos específicos de la operación

Campos de Respuesta

Campo	Tipo	Descripción
global_seq	entero	Número de secuencia global del commit
batch_seq	entero	Número de secuencia del lote
minted_instances	array	IDs de las instancias creadas por MintInstance
metadata	objeto	Eco de los metadatos de la solicitud, incluyendo idempotency_key

Ejemplos

Transacción Mínima

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": "Standard",
        "owner": null
      }
    }
  ]
}

Transacción con Idempotencia

{
  "operations": [
    {
      "op": "AddFungible",
      "args": {
        "container_id": 1001,
        "class_id": 100,
        "key": 1,
        "quantity": 500
      }
    }
  ],
  "idempotency_key": "add-balance-2024-01-15-001"
}

Transacción de Múltiples Operaciones

{
  "operations": [
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "name": "Sample",
          "fungible": false
        }
      }
    },
    {
      "op": "MintInstance",
      "args": {
        "class_id": 200,
        "key": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "instance_id": 9001,
        "slot_index": 0
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Respuesta:

{
  "global_seq": 5,
  "batch_seq": 1,
  "minted_instances": [9001],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Respuesta de Reintento Idempotente

Cuando se envía nuevamente la misma clave de idempotencia:

{
  "global_seq": 5,
  "batch_seq": 1,
  "minted_instances": [9001],
  "metadata": {
    "idempotency_key": "create-sample-001"
  }
}

El encabezado X-Asset-Idempotency: hit indica una respuesta en caché.

Referencias relacionadas

5. Operaciones por Dominio - Referencia completa de operaciones
6. Recetas - Patrones comunes de múltiples operaciones

• Modelo de Error - Manejo de fallos en transacciones