SAP Explorer Docs
SDK Reference

Event System

Parse and filter on-chain events from SAP program transaction logs.

Event System

The SAP program emits 45 event types through Solana transaction logs. The SDK provides an EventParser that decodes these logs into typed objects for real-time monitoring, analytics, and webhooks.

Why Events?

On-chain accounts show current state but not history. Events capture every state transition: when an agent registered, when an escrow was funded, when a payment was settled. This is essential for:

  • Audit trails: Prove when and how an action happened.
  • Real-time dashboards: Stream events via WebSocket for live updates.
  • Off-chain sync: Mirror on-chain state to PostgreSQL (see PostgreSQL Mirror docs).
  • Webhooks: Trigger external actions when specific events occur.

EventParser

Access via client.events. The parser deserializes Anchor event logs from confirmed transactions.

Parse Transaction Logs

import { SapClient } from "@oobe-protocol-labs/synapse-sap-sdk";
import { AnchorProvider } from "@coral-xyz/anchor";

const client = SapClient.from(AnchorProvider.env());

// Get a confirmed transaction's logs
const tx = await client.program.provider.connection.getTransaction(
  "txSignature...",
  { commitment: "confirmed", maxSupportedTransactionVersion: 0 },
);

if (tx?.meta?.logMessages) {
  // parseLogs decodes all SAP events from the log messages.
  // Returns an array of { name, data } objects.
  const events = client.events.parseLogs(tx.meta.logMessages);

  for (const event of events) {
    console.log("Event:", event.name);   // e.g. "RegisteredEvent"
    console.log("Data:", event.data);    // typed event payload
  }
}

Filter by Event Name

// Filter for specific event types.
const settlements = client.events.filterByName(events, "PaymentSettledEvent");

for (const event of settlements) {
  console.log("Agent:", event.data.agent);
  console.log("Depositor:", event.data.depositor);
  console.log("Amount:", event.data.amount);
  console.log("Calls:", event.data.callCount);
}

Event Reference

Agent Events

Event NameEmitted WhenKey Fields
RegisteredEventAgent registeredwallet, name, agentPda
UpdatedEventAgent profile updatedwallet, fields
DeactivatedEventAgent deactivatedwallet, agentPda
ReactivatedEventAgent reactivatedwallet, agentPda
AgentClosedEventAgent account closedwallet, rentReclaimed

Feedback Events

Event NameEmitted WhenKey Fields
FeedbackGivenEventFeedback submittedagent, reviewer, score, tag
FeedbackUpdatedEventFeedback score changedagent, reviewer, newScore
FeedbackRevokedEventFeedback revokedagent, reviewer

Tool Events

Event NameEmitted WhenKey Fields
ToolPublishedEventTool descriptor createdagent, toolName, category
ToolUpdatedEventTool descriptor updatedagent, toolName, version
SchemaInscribedEventSchema inscribed to TX logagent, toolName, schemaType

Memory Events

Event NameEmitted WhenKey Fields
VaultInitializedEventVault createdagent, nonce
SessionOpenedEventSession startedvault, sessionId
MemoryInscribedEventData inscribed to vaultsession, sequence, size
LedgerEntryEventLedger write completedsession, dataSize, hash
LedgerSealedEventLedger page sealedledger, pageIndex
DelegateAddedEventVault delegate grantedvault, delegate, permissions
DelegateRevokedEventVault delegate revokedvault, delegate
CheckpointCreatedEventSession checkpoint savedsession, tag, merkleRoot

Payment Events

Event NameEmitted WhenKey Fields
EscrowCreatedEventEscrow account fundedagent, depositor, deposit
EscrowDepositEventAdditional funds depositedagent, depositor, amount
PaymentSettledEventPayment claimed by agentagent, depositor, amount, calls
EscrowWithdrawnEventFunds withdrawn by depositoragent, depositor, amount
EscrowClosedEventEscrow account closedagent, depositor, rentReclaimed

Attestation Events

Event NameEmitted WhenKey Fields
AttestationCreatedEventAttestation issuedattester, subject, type
AttestationRevokedEventAttestation revokedattester, subject

Discovery Events

Event NameEmitted WhenKey Fields
CapabilityIndexedEventAgent added to cap indexagent, capability
ProtocolIndexedEventAgent added to protocol indexagent, protocol
ToolCategoryIndexedEventTool added to categorytool, category

Event Names Constant

import { SAP_EVENT_NAMES } from "@oobe-protocol-labs/synapse-sap-sdk";

// SAP_EVENT_NAMES is an array of all 45 event name strings.
// Useful for filtering or building event subscription maps.
console.log(SAP_EVENT_NAMES.length); // 45

WebSocket Streaming

For real-time event monitoring, subscribe to program logs via WebSocket:

const connection = client.program.provider.connection;

// Subscribe to all logs from the SAP program.
const subscriptionId = connection.onLogs(
  client.program.programId,
  (logs) => {
    if (logs.err) return;  // skip failed TXs

    const events = client.events.parseLogs(logs.logs);
    for (const event of events) {
      console.log(`[${event.name}]`, event.data);
      // Route to your webhook, database, or dashboard
    }
  },
  "confirmed",
);

// Unsubscribe when done
await connection.removeOnLogsListener(subscriptionId);