Transaccions i Operacions

Les transaccions són la unitat atòmica de canvi a Asset Core. Cada transacció conté una seqüència d’operacions que s’executen juntes o no s’executen en absolut.

Problema que resol aquest concepte

Els canvis d’estat complexos sovint requereixen múltiples actualitzacions coordinades:

• Creant un contenidor i omplint-lo
• Transferència d’actius entre ubicacions
• Creant una instància i col·locant-la

Sense transaccions atòmiques, aquests canvis de múltiples passos podrien fallar a mitja execució, deixant el sistema en un estat inconsistent. Asset Core resol això agrupant operacions en transaccions amb semàntica de tot o res.

A més, els agents d’IA necessiten un conjunt d’operacions limitat i segur. Les API obertes permeten als agents fer canvis perillosos. Un vocabulari d’operacions fix et permet auditar i restringir el comportament dels agents.

Idees principals

Estructura del Compromís

Una sol·licitud de commit conté una llista d’operacions:

{
  "operations": [
    { "op": "CreateContainer", "args": { ... } },
    { "op": "AddFungible", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key"
}

Les operacions s’executen en ordre dins de la transacció. Si qualsevol operació falla, tota la confirmació es desfarà.

Operació Envelope

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

{
  "op": "OperationName",
  "args": { ... }
}

• op: L’identificador de l’operació (per exemple, CreateContainer)
• args: Arguments específics de l’operació

Aquesta estructura uniforme facilita la composició i el processament d’operacions de manera programàtica.

Les 16 Operacions

Asset Core defineix exactament 16 operacions a través de 5 dominis:

Domini	Operacions
Contenidor	CrearContenidor, EliminarContenidor
Balanç	AfegirFungible, EliminarFungible, TransferirFungible, FusionarPiles, ConsolidarPiles
Instància	MuntarInstància, CremarInstància, Adjuntar, Desadjuntar
Slot	Col·locarEnSlot, TreureDeSlot, IntercanviarSlots
Esquema	RegistrarClasse, RegistrarFormaClasse

Aquest conjunt fix és intencionat. Proporciona:

• Auditabilitat: Cada possible canvi d’estat és conegut
• Seguretat: No hi ha mutacions arbitràries
• Consistència: Mateixes operacions funcionen a tots els entorns

Sistema de Etiquetes

Les operacions es classifiquen en quatre dimensions:

Dominis: Quin tipus d’entitat està afectat

• contenidor, saldo, instància, slot, esquema

Acció: Quin tipus de canvi

• crear, destruir, moure, enllaçar, consolidar

Abast: Quantes entitats

• single, multi

Reversibilitat: Es pot desfer?

• reversible, destructive, neutral

Les etiquetes t’ajuden a:

• Operacions de filtratge per a permisos d’agent
• Entendre la natura dels canvis
• Construir eines al voltant dels tipus d’operació

Idempotència

La idempotency_key opcional permet reintents segurs:

• La primera sol·licitud amb una clau s’executa normalment
• Les sol·licituds posteriors amb la mateixa clau retornen la resposta emmagatzemada
• Prevé la duplicació de commits a causa de reintents de xarxa

Sempre utilitzeu claus d’idempotència per a càrregues de treball en producció.

Com s’integra al sistema

Flux d’Execució

1. El client envia una sol·licitud de compromís
2. Escriure daemon que analitza i valida
3. Les operacions s’executen en seqüència
4. Els esdeveniments es registren per a cada operació
5. Els esdeveniments es segellen en un lot
6. El lot es persisteix al registre de confirmacions
7. El client rep una resposta d’èxit

Reversió en cas de fallada

Si alguna operació falla:

L’execució s’atura en l’operació fallida 2. El registre d’anul·lació s’aplica en ordre invers 3. L’estat es restaura a la situació anterior a la transacció 4. El client rep una resposta d’error

No hi ha compromisos parcials visibles per als lectors.

Generació d’Esdeveniments

Cada operació genera esdeveniments que:

• Descriu el canvi d’estat
• Portar l’estat posterior per a la reproducció
• S’agrupen en el lot de transaccions

Els esdeveniments són el registre durable; les operacions són el format de sol·licitud.

Invariants i garanties clau

Atomicitat

Totes les operacions en una transacció tenen èxit o fracassen juntes:

• No s’executa cap parcial visible
• La reversió restaura l’estat anterior exacte
• Les respostes d’error indiquen quina operació ha fallat

Conservació de l’Ordre

Les operacions s’executen en l’ordre de l’array:

• Les operacions posteriors veuen els efectes de les anteriors
• Les dependències es satisfan de manera seqüencial
• Sense reordenament ni execució paral·lela

Determinisme

Les mateixes operacions produeixen els mateixos esdeveniments:

• Donades les mateixes condicions i operacions
• Els esdeveniments seran idèntics en bytes
• Permet la reproducció i la verificació

Vocabulari Fixat

No es poden afegir operacions personalitzades:

• Les 16 operacions estan completes
• Els canvis complexos componen múltiples operacions
• Aquesta restricció és una característica, no una limitació

Veure també

• Transaccions - referència de l’estructura JSON
• Operacions per Domini - Detalls complets de l’operació

5. Receptes - Patrons comuns de múltiples operacions