Saltar al contenido principal

Eventos

Los eventos son el mecanismo que las aplicaciones fuera de la cadena pueden usar para monitorear cambios y eventos en contratos dentro de la cadena.

¿Cómo se emiten los eventos?​

ContractEvents se emiten en TransactionMeta de Stellar Core. Puedes ver en el XDR de TransactionMetaV3 a continuación que hay una lista de OperationEvents llamada events. Cada OperationEvent corresponde a una operación en una transacción y contiene, a su vez, una lista de ContractEvents. Ten en cuenta que events solo se completará si la transacción tiene éxito. Consulta las guías de eventos y este ejemplo para aprender más sobre cómo trabajar con eventos.

información

Los eventos son efímeros, la ventana de retención de datos es un máximo de 7 días. Consulta la guía de ingestión para aprender cómo trabajar con esta limitación.

ContractEvent​

Los temas de los eventos no tienen que ser del mismo tipo. Puedes mezclar diferentes tipos.

Un evento también contiene un objeto de datos de cualquier valor o tipo, incluidos los tipos definidos por contratos usando #[contracttype]

struct ContractEvent
{
    // We can use this to add more fields, or because it
    // is first, to change ContractEvent into a union.
    ExtensionPoint ext;

    Hash* contractID;
    ContractEventType type;

    union switch (int v)
    {
    case 0:
        struct
        {
            SCVec topics;
            SCVal data;
        } v0;
    }
    body;
};

OperationEvents​

struct OperationEvents
{
    ContractEvent events<>;
};

TransactionMetaV3​

struct TransactionMetaV3
{
    LedgerEntryChanges txChangesBefore; // tx level changes before operations
                                        // are applied if any
    OperationMeta operations<>;         // meta for each operation
    LedgerEntryChanges txChangesAfter;  // tx level changes after operations are
                                        // applied if any
    OperationEvents events<>;           // custom events populated by the
                                        // contracts themselves. One list per operation.
    TransactionResult txResult;

    Hash hashes[3];                     // stores sha256(txChangesBefore, operations, txChangesAfter),
                                        // sha256(events), and sha256(txResult)

    // Diagnostics events that are not hashed. One list per operation.
    // This will contain all contract and diagnostic events. Even ones
    // that were emitted in a failed contract call.
    OperationDiagnosticEvents diagnosticEvents<>;
};

Enlace al XDR anterior.

Tipos de eventos​

Hay tres tipos de ContractEventType -

  1. Los eventos CONTRACT son eventos emitidos por contratos que utilizan la función host contract_event para transmitir cambios de estado.
  2. Los eventos SYSTEM son eventos emitidos por el host. En este momento, solo hay un evento del sistema emitido por el host. Se emite cuando se llama a la función host update_current_contract_wasm, donde topics = ["executable_update", old_executable: ContractExecutable, old_executable: ContractExecutable] y data = [].
  3. Los eventos DIAGNOSTIC están destinados a la depuración y no se emitirán a menos que la instancia del host lo habilite explícitamente. Puedes leer más sobre esto a continuación.

¿Qué son los diagnosticEvents?​

Mientras observas la estructura XDR de TransactionMetaV3 anterior, es posible que hayas notado el campo diagnosticEvents. Esta lista estará vacía por defecto a menos que tu instancia de stellar-core tenga ENABLE_SOROBAN_DIAGNOSTIC_EVENTS=true en su archivo de configuración. Si se habilitan eventos de diagnóstico, esta lista no solo incluirá todos los ContractEvents en events, sino que también incluirá eventos de llamadas a contratos fallidas, errores del host, eventos para rastrear la pila de llamadas de contratos y registros de la función host log_from_linear_memory. Estos eventos pueden identificarse por type == DIAGNOSTIC. Los eventos de diagnóstico emitidos por el host para rastrear la pila de llamadas se definen a continuación.

fn_call​

El evento de diagnóstico fn_call se emite cuando se llama a un contrato y contiene -

  • Temas
    1. El símbolo "fn_call".
    2. El id del contrato que está a punto de ser llamado.
    3. Un símbolo que contiene el nombre de la función que se está llamando.
  • Datos
    1. Un vector de los argumentos pasados a la función que se está llamando.

fn_return​

El evento de diagnóstico fn_return se emite cuando una llamada a contrato se completa y contiene -

  • Temas
    1. El símbolo "fn_return".
    2. Un símbolo que contiene el nombre de la función que está a punto de devolver.
  • Datos
    1. El valor devuelto por la función del contrato.

¿Cuándo se deben habilitar los eventos de diagnóstico?​

events contiene ContractEvents que deben transmitir información sobre cambios de estado. diagnosticEvents, por otro lado, contienen eventos que no son útiles para la mayoría de los usuarios, pero pueden ser útiles para depurar incidencias o construir la pila de llamadas del contrato. Dado que no serán utilizados por la mayoría de los usuarios, pueden habilitarse opcionalmente porque no están encriptados en el ledger y, por lo tanto, no son parte del protocolo. Esto se hace para que un nodo de stellar-core pueda mantenerse sincronizado con la red mientras emite estos eventos que normalmente no serían útiles para la mayoría de los usuarios.

Debido a que un nodo con eventos de diagnóstico habilitados ejecutará caminos de código que divergen de un nodo regular, te recomendamos encarecidamente que uses esta función solo en nodos de observación (nodos donde se establece NODE_IS_VALIDATOR=false).