Zum Inhalt

Events (Ereignisse)

Ereignisse sind unveränderliche, überprüfbare Objekte, die von den Smart Contracts emittiert, von der Alephium-Full-Node gespeichert und bereitgestellt werden. Sie spielen eine entscheidende Rolle bei der effizienten und transparenten Kommunikation zwischen Smart Contracts und Off-Chain-Anwendungen.

Es gibt viele Anwendungsfälle für Ereignisse: Eine dezentrale Börse kann Ereignisse verwenden, um alle Swap-Vorgänge in einem Token-Paar zu verfolgen. Ein NFT-Marktplatz kann Ereignisse verwenden, um alle NFT-Angebote zu speichern. Ein Oracle kann Ereignisse verwenden, um Anfragen nach bestimmten Off-Chain-Informationen von Smart Contracts zu signalisieren. Eine Bridge kann Ereignisse verwenden, um bestimmte Aktionen darzustellen, die die Zustimmung aller Bridge-Betreiber erfordern, usw.

Ereignisobjekt

Ein Ereignisobjekt in Alephium besteht aus den folgenden Attributen:

Text Only
txId            : Transaktions ID
blockHash       : Block Hash
contractAddress : Adresse des Vertrags, in dem das Ereignis ausgelöst wird / Spezielle Adresse für Systemereignisse
eventIndex      : Index des Ereignisses, das vom Vertrag ausgelöst wird / Spezieller Index für Systemereignisse
fields          : Felder, die im Ereignis enthalten sind

Es gibt zwei Arten von Ereignissen in Alephium: Vertragsereignisse and Systemereignisse. Die folgenden Abschnitte behandeln sie jeweils mit weiteren Details zu den Attributen contractAddress, eventIndex und fields attributes.

Vertragsereignisse

Wie der Name schon sagt, handelt es sich bei Vertragsereignissen um benutzerdefinierte Ereignisse, die von den Verträgen emittiert werden:

Event/AdminUpdated
Rust
Contract Admin(mut admin: Address) {
  event AdminUpdated(previous: Address, new: Address)

  @using(updateFields = true)
  pub fn updateAdmin(newAdmin: Address) -> () {
      checkCaller!(callerAddress!() == admin, 0)

      admin = newAdmin
      emit AdminUpdated(admin, newAdmin)
  }
}

In diesem Beispiel wird jedes Mal, wenn admin aktualisiert wird, ein AdminUpdated-Ereignis ausgelöst. Diese Informationen können von Off-Chain-Anwendungen abgehört werden, um ihre Benutzeroberflächen zu aktualisieren oder für Überprüfungszwecke.

Sie können alle von einem Vertrag ausgesendeten Ereignisse abonnieren oder ein bestimmtes Ereignis, das von einem Vertrag ausgesendet wird, mit dems Web3 SDK von Alephium abonnieren:

Event/AdminUpdatedEvent
TypeScript
// `adminInstance` ist eine Vertragsinstanz des Admin-Vertrags.
adminInstance.subscribeAdminUpdatedEvent({
  pollingInterval: 500,
  messageCallback: (event: AdminTypes.AdminUpdatedEvent): Promise<void> => {
    console.log('got admin updated event:', event)
    return Promise.resolve()
  },
  errorCallback: (error: any, subscription): Promise<void> => {
    console.log(error)
    subscription.unsubscribe()
    return Promise.resolve()
  }
})

Im Ereignisobjekt von AdminisUpdated repräsentiert contractAddress die Vertragsadresse von adminInstance, eventIndex ist 0 da AdminUpdated idas erste definierte Ereignis im Admin contract (0-based index). fields enthält zwei Adressen: eine für den vorherigen Administrator und eine für den neuen Administrator.

Systemereignisse

Im Vergleich zu den Vertragsereignissen, die explizit von den Verträgen emittiert werden, werden Systemereignisse automatisch von der Alephium-Full-Node emittiert. Derzeit gibt es zwei Systemereignisse:

ContractCreatedEvent

ContractCreatedEvent wird ausgelöst, wenn ein neuer Vertrag erstellt wird:

Rust
TxScript Deploy(fooByteCode: ByteVec) {
  createContract!{callerAddress!() -> ALPH: 1 ALPH}(fooByteCode, #00, #00)
}

Im obigen Beispiel erstellt das Deploy -Transaktionsskript einen neuen Foo-Vertrag aus seinem Vertrags-Bytecode. Der Foo-Vertrag hat keine Vertragsfelder, weshalb #00 als Argumente an die createContract-Funktion übergeben werden. EinContractCreatedEvent Systemereignis wird ausgelöst, nachdem der Foo-Vertrag erstellt wurde.

Alephium's Web3 SDK bietet eine Hilfsfunktion zum Abonnieren des Ereignisses ContractCreatedEvent:

ContractCreatedEvent
TypeScript
subscribeContractCreatedEvent({
  pollingInterval: 500,
  messageCallback: (event: ContractCreatedEvent): Promise<void> => {
    console.log('got contract created event:', event)
    return Promise.resolve()
  },
  errorCallback: (error: any, subscription): Promise<void> => {
    console.log(error)
    subscription.unsubscribe()
    return Promise.resolve()
  }
})

Im Ereignisobjekt von ContractCreatedEvent, ist eventIndex auf -1 gesetzt, ein Wert, der speziell für das Ereignis ContractCreatedEvent reserviert ist. contractAddress ist auf einen speziellen Wert gesetzt, der basierend auf dem eventIndex und der Vertragsgruppe berechnet wird. fields enthält die Adresse des neu erstellten Vertrags sowie dessen übergeordnete Vertrags-ID, sofern vorhanden.

ContractDestroyedEvent

ContractDestroyedEvent wird ausgelöst, wenn ein Vertrag zerstört wird:

Rust
Contract Foo() {
  @using(assetsInContract = true)
  pub fn destroy() -> () {
    destroySelf!(callerAddress!())
  }
}

Im obigen Beispiel, nachdem die destroy-Funktion aufgerufen wurde, wird der Foo-Vertrag zerstört und ein ContractDestroyedEvent-Systemereignis wird vom Alephium-Fullknoten ausgelöst.

Alephium's Web3 SDK bietet eine Hilfsfunktion zum Abonnieren des Ereignisses ContractDestroyedEvent:

ContractDestroyedEvent
TypeScript
subscribeContractDestroyedEvent({
  pollingInterval: 500,
  messageCallback: (event: ContractDestroyedEvent): Promise<void> => {
    console.log('got contract destroyed event:', event)
    return Promise.resolve()
  },
  errorCallback: (error: any, subscription): Promise<void> => {
    console.log(error)
    subscription.unsubscribe()
    return Promise.resolve()
  }
})

Im Ereignisobjekt von ContractDestroyedEvent ist, eventIndex ist -2, festgelegt, ein Wert, der speziell für das Ereignis ContractDestroyedEvent reserviert ist. contractAddress ist auf einen speziellen Wert festgelegt, der basierend auf dem eventIndex und der Vertragsgruppe berechnet wird. fields enthält die Adresse des zerstörten Vertrags.

Konfiguration

Alephiums Full Node ermöglicht eine flexible Konfiguration, wie Ereignisse gespeichert und indiziert werden sollen. Standardmäßig werden Ereignisse nicht gespeichert, um den Full Node schlank zu halten.

Sie können das Speichern von Ereignissen mithilfe des folgenden Flags aktivieren:

Text Only
alephium.node.event-log.enabled=true

Dies ermöglicht es uns, Vertragsereignisse und Systemereignisse basierend auf der Vertragsadresse abzufragen.

Um die Abfrage von Ereignissen basierend auf Transaktions-ID und Block-Hash zu ermöglichen, müssen Sie die folgenden Flags aktivieren:

Text Only
alephium.node.event-log.index-by-tx-id = true
alephium.node.event-log.index-by-block-hash = true

Standardmäßig werden Ereignisse, die von allen Verträgen ausgegeben werden, gespeichert. Wenn Sie jedoch wissen, für welche Verträge Sie Ereignisse erhalten möchten, können Sie die folgende Konfiguration verwenden:

Text Only
alephium.node.event-log.contract-addresses = [$CONTRACT_ADDR_1, $CONTRACT_ADDR_2]

Auf diese Weise sparen Sie Speicherplatz, da Ihr Full Node nur die Ereignisse speichert, die von den hier angegebenen Verträgen ausgegeben wurden.

Weiterführende Literatur

Die Ereignisabonnementfunktionen im Web3 SDK abasieren auf den APIs des Alephium-Full-Nodes. Weitere Details zu den APIs finden Sie in der OpenAPI Dokumentation.

Neben ContractEvent und SystemEvent, gibt es tatsächlich ein weiteres (spezielles) Systemereignis namens DebugEvent. Bitte beachten Sie Debugging für weitere Informationen.