Transaccions

Una transacció és una llista d’operacions que s’executen de manera atòmica. Aquesta referència descriu l’estructura JSON de les sol·licituds de confirmació.

Visió general

Tots els canvis d’estat flueixen a través del punt d’entrada /v1/commit com a transaccions. El daemon d’escriptura valida, executa i persisteix les operacions abans de retornar una resposta d’èxit.

Estructura

Sol·licitud de Compromís

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

Operació Envelope

Cada operació té la mateixa estructura d’envolupant:

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

Camps

Camps de sol·licitud

Camp	Tipus	Requerit	Descripció
operations	array	Sí	Llista d’operacions a executar
idempotency_key	string	No	Clau única per a la deduplicació
metadata	objecte	No	Metadades definides per l’usuari reflectides a la resposta

Camps d’Operació Envelope

Camp	Tipus	Requerit	Descripció
op	cadena	Sí	Identificador de l’operació
args	objecte	Sí	Arguments específics de l’operació

Camps de resposta

Field	Type	Description
global_seq	integer	Número de seqüència global del commit
batch_seq	integer	Número de seqüència del lot
minted_instances	array	IDs d’instàncies creades per MintInstance
metadata	object	Eco de la metadata de la sol·licitud, incloent idempotency_key

Exemples

Transacció Mínima

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

Transacció amb Idempotència

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

Transacció Multi-Operació

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

Resposta:

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

Resposta de Reintents Idempotents

Quan la mateixa clau d’idempotència s’envia de nou:

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

L’encapçalament X-Asset-Idempotency: hit indica una resposta emmagatzemada en caché.

Referències relacionades

5. Operacions per Domini - Referència completa d’operacions
6. Receptes - Patrons comuns de múltiples operacions

• Model d’Error - Gestió de fallades en transaccions