CDS pluginCDS plugintypeInstalls into a CAP project and extends the runtime. CAP loads it through cds.requires or the plugin hook.See every one →What this type is →independently maintainedindependently maintainedoriginPublished by one person or a small company outside SAP. Says nothing about quality; the readings say that.See every one →
@odatano/watch
Watches Cardano addresses, payment credentials and minting policies from inside CAP, emitting events with full UTxO payloads and persisting them so a missed window can be replayed.
Persistence for replay is what makes it a CAP plugin rather than a webhook: the chain does not resend, so the record of what was seen has to live somewhere the application can re-read.
Async processingCAPAsync processingcapabilityDoing work outside the request that triggered it, with a guarantee that it eventually happens — deferred jobs, retries, and periodic work. Distinct from messaging, which is about telling other systems.
@sap/cds≥ 9.0.0@sap/cdsartifactThe peer range, as published.
Who is behind it
ODATANOODATANOOrganisationMaintains this In the atlas: maintains 4@ODATANOmaintainerMaxPersonContributes to this In the atlas: contributes to 4@maxalexweber11 contributor
Before choosing this
crawled
Conditions
LicenceSAP Developer License Agreement 3.2 CAP§ 1, 2, 3A cds-plugin is used with SAP CAP materials, or an artifact is explicitly identified as a CAP plugin or application.
Derived: the instrument's applicability matches this artifact, checked
§ 1License. Productive customer applications are limited to SAP BTP or another SAP-licensed platform, and mass extraction to a non-SAP product is restricted except where solely required for SAP interoperability.
§ 2Intellectual Property. The agreement retains SAP's rights in the covered materials and limits making APIs, tools or software available to third parties, while preserving ownership of customer applications subject to SAP's underlying rights.
§ 3Artificial Intelligence Training. The agreement prohibits use of the covered materials and customer applications for training artificial-intelligence models or systems.
Also, from Async processing§ 1: Messaging is not automatically mass extraction, but an external broker can cross the boundary named in section 1. The data flow, volume and interoperability purpose therefore need to be checked for the concrete design.
What it declares
Every artifact
Type
CDS plugin
Origin
Independently maintained
Runtime
Node.js
declared
As a CDS plugin
Declared for
>=9.0.0
declared, the peer range, as published
Distributed through
npm
declared, How the plugin is installed into a CAP project, as its documentation says., read npm add @odatano/watch — @odatano/watch — README, 2026-10-18
Connections1
Group by
NodeRelationConditionBasis
Functional1
Async processingAsync processingcapabilityDoing work outside the request that triggered it, with retriesSAP and community, narrow by design
→provides
none
authored
provides Async processing
Functional, authored
Doing work outside the request that triggered it, with retries
CAP plugin for monitoring the Cardano blockchain. Watches addresses, payment credentials, and minting policies; emits events with rich UTxO payloads (assets, inline datums, reference scripts) and persists them for replay.
Credential and policy watching are off by default — opt in via credentialPolling / policyPolling. Credential watching also needs a (free-tier-OK) Koios endpoint. See Quick Start for the full config.
Secrets via environment variables
To keep the API key out of package.json, leave the field unset and export the env var instead — the plugin picks it up as a fallback:
Other recognized env vars: BLOCKFROST_CUSTOM_BACKEND, KOIOS_API_KEY, OGMIOS_URL, WATCHER_BACKEND. cds.env.requires.watch.<field> always wins when set.
Self-hosted Blockfrost (Dolos / cardano-node)
Polling burns through the Blockfrost free-tier daily quota quickly. To route the SDK at a self-hosted Blockfrost-compatible endpoint instead, set blockfrostCustomBackend (and drop blockfrostApiKey):
http://localhost:3100/api/v0 is the default for Dolos's MiniBF. Equivalent env var: BLOCKFROST_CUSTOM_BACKEND. Public Blockfrost stays the default when this field is unset.
Subscribe to events
import type { NewTransactionsEvent, CredentialNewTransactionsEvent, PolicyAssetMintedEvent,} from "@odatano/watch";cds.on("cardano.newTransactions", async (e: NewTransactionsEvent) => { // e.address, e.tag?, e.transactions[], e.utxosCreated[], e.utxosSpent[] for (const utxo of e.utxosCreated) { if (utxo.inlineDatumHex) await applyDatum(utxo.inlineDatumHex); }});cds.on("cardano.credential.newTransactions", async (e: CredentialNewTransactionsEvent) => { /* ... */ });cds.on("cardano.policy.assetMinted", async (e: PolicyAssetMintedEvent) => { /* ... */ });
Other emitted events: cardano.policy.assetBurned, and (Phase 2 / Ogmios only) cardano.rollback.
Read Event Delivery Semantics before building stateful consumers — there are guarantees we don't make (no cross-handler ordering, no retry, no backpressure) and a checklist of patterns to follow.
POST /odata/v4/cardano-watcher-admin/getEventsSinceContent-Type: application/json{ "scope": "address", "key": "addr_test1...", "fromBlock": 12345 }
Returns persisted BlockchainEvent rows ordered by blockHeight asc. Use the last returned blockHeight as the next call's fromBlock for cursor pagination.
Phase 2 — Ogmios chainSync
Set backend: 'ogmios' and ogmiosUrl: 'ws://localhost:1337' to switch from polling to a chainSync stream with native rollback signal. Backfill from Blockfrost runs once per new watch. See Architecture → Phase 2 for caveats.
Bugfix release. Two issues prevented consumers from running the plugin against the README-documented config: the plugin patched the wrong requires-key, and env-var fallback names did not match the README naming.
Fixed
Plugin requires-key mismatch — entities not deployed (Blocker). README documented cds.requires.watch but src/plugin.ts registered the kind as cardano-watcher and patched cds.env.requires['cardano-watcher']. The if (reqEntry) guard never fired for consumers using the README config, so the plugin's model array was never set on the requires entry. Result: cds deploy never generated DDL for WatcherCursor / WatchedCredential / WatchedAddress / WatchedPolicy / BlockchainEvent / TransactionSubmission / WatcherConfig, and the polling loop crashed with no such table: CardanoWatcherAdminService_WatchedCredentials. Plugin now registers the kind as watch and patches cds.env.requires['watch'], matching the README.
Changed
Env-var fallback names aligned with README naming.BLOCKFROST_KEY → BLOCKFROST_API_KEY, KOIOS_KEY → KOIOS_API_KEY. BLOCKFROST_CUSTOM_BACKEND, OGMIOS_URL, WATCHER_BACKEND unchanged. Consumers can now leave the field out of package.json and export the env var instead — the plugin reads it directly when cds.env.requires.watch.<field> is unset. Documented in README.md and docs/SETUP.md.
Docs: removed broken ${VAR} substitution pattern. Previous docs/SETUP.md suggested "blockfrostApiKey": "${BLOCKFROST_KEY}" — CAP's env loader does not substitute ${...} placeholders inside cds.requires.*, so this pattern always produced a literal "${BLOCKFROST_KEY}" string at runtime. Replaced with the env-var fallback path described above.
Breaking (semantic)
Consumers who were using cds.requires.cardano-watcher as the requires key (i.e. matching the pre-0.1.8 plugin code rather than the README) must rename to cds.requires.watch. Anyone following the documented config is unaffected.
Consumers using BLOCKFROST_KEY / KOIOS_KEY env vars must rename to BLOCKFROST_API_KEY / KOIOS_API_KEY. No alias is kept.
Adds support for routing the Blockfrost SDK at a self-hosted Blockfrost-compatible endpoint (e.g. Dolos's MiniBF) instead of the public Blockfrost service. Polling-heavy deployments would otherwise burn through the public free-tier daily quota; pointing at a local MiniBF removes the ceiling entirely.
Added
blockfrostCustomBackend config field (src/config.ts, src/blockfrost.ts). When set, the Blockfrost SDK is constructed with customBackend instead of the public-network preset, and blockfrostApiKey becomes optional. Env fallback: BLOCKFROST_CUSTOM_BACKEND. Default for Dolos's MiniBF is http://localhost:3100/api/v0.
README and docs/SETUP.md / docs/QUICKSTART.md updated with the self-hosted Blockfrost setup.
Unit tests in test/unit/blockfrost.test.ts, test/unit/config.test.ts, test/unit/watcher.test.ts covering the custom-backend code path (constructor wiring, config resolution, API-key-optional case).
Hotfix release. 0.1.5 shipped with a stale path in the CAP plugin entry — the package boot-crashes on npm install for any consumer.
Fixed
cds-plugin.js references the pre-0.1.5 layout (Blocker). The 0.1.5 packaging migration updated package.json.main from dist/src/index.js to src/index.js, but cds-plugin.js (a separate CAP plugin entry, not generated from TS) was missed and still required ./dist/src/plugin — a path that no longer exists after the in-place build. Result: MODULE_NOT_FOUND on every CAP startup. One-line fix to require('./src/plugin').
Maintenance
.gitignore: ignore the in-place build artifacts (src/**/*.js, src/**/*.d.ts, srv/**/*.js, srv/**/*.d.ts) so they're shipped in the npm tarball but not tracked in git.
Bugfix release covering four blocker/major issues that prevented a clean out-of-the-box experience after the 0.1.4 feature wave. No new features.
Fixed
Packaging — srv/admin-service not loadable from a fresh install (Blocker). Previous tarball shipped srv/admin-service.ts only; CAP's @impl: '@odatano/watch/srv/admin-service' couldn't resolve a .js file. Switched to in-place compilation via new tsconfig.build.json (outDir: "."). Now srv/admin-service.js ships alongside the source.
Packaging — #cds-models/... runtime require failed for consumers (Blocker). Replaced require('#cds-models/CardanoWatcherAdminService') with literal relative path require('../@cds-models/CardanoWatcherAdminService/index.js'). @cds-models/ directory now ships in the tarball. Consumers no longer need to mirror an imports field in their own package.json.
Koios endpoint /credential_address does not exist (Blocker). getAddressesByCredential now hits /credential_utxos (the only Koios endpoint that returns addresses for a credential), dedups by row.address, and paginates via Range header. Caveat: returns only currently-unspent addresses — sufficient for credential watching's filter-set use case.
Hot script credentials triggered genesis-backfill stampede (Major). addWatchedAddress / addWatchedCredential / addWatchedPolicy now default lastCheckedBlock to the current Blockfrost tip (was null, which made the first poll fetch from genesis). Hits Koios's pagination cap on creds with millions of historical txs (Minswap V2, etc.) are no longer the OOTB experience. Under Ogmios mode the cursor stays null so the chainSync-cap'd backfill can still run.
backfill.ts ESLint failure — overengineered infer _ conditional type replaced with direct type imports.
Changed
Build pipeline: tsc → tsc -p tsconfig.build.json. New build:typecheck script runs the original (no-emit) tsc for IDE-style verification.
package.json:
main: dist/src/index.js → src/index.js
types: dist/src/index.d.ts → src/index.d.ts
files array: explicit globs (*.js, *.d.ts, *.cds) instead of directory entries — strips .ts source from the published tarball (65 → 45 files).
TypeScript module resolution: moduleResolution: "node" (deprecated alias) → "node16". module aligned to "node16". Two dynamic import('./index') calls in src/plugin.ts updated to import('./index.js'). Jest gains a moduleNameMapper to strip .js suffixes back to TS source for compile-on-the-fly tests.
Breaking (semantic)
Watch-add no longer backfills history by default. A freshly-added watch sees only forward activity (from the current Blockfrost tip onward). This is the corrected behavior — previous "default to genesis" caused the OOTB stampede. Consumers needing history can call backfill.backfillAddress() / backfillCredential() / backfillPolicy() programmatically, or PATCH the watch entity to set an earlier lastCheckedBlock.
WatchedCredential entity (P1) — watch a payment credential across every bech32 derivative that shares it. Required for shared-script watching (Indigo CDP-manager, Minswap V2 pools, etc.). Backed by Koios for credential→addresses resolution.
WatchedPolicy entity (P4) — watch a minting policy for mint/burn events. Suited to stablecoin/utility-token policies; high-asset NFT policies refused via policyAssetCap (default 100).
Event payloads (P2 / P3 / P5)
cardano.newTransactions payload extended in-place with tag, utxosCreated[], utxosSpent[]. UTxO entries carry lovelace, assets[], and (when present) inlineDatumHex and referenceScriptHash.
New event cardano.credential.newTransactions — same UTxO-rich shape, scoped to a payment credential.
New events cardano.policy.assetMinted and cardano.policy.assetBurned — per-event semantics, payload { policyId, tag?, assetNameHex, quantity, txHash, blockHeight }.
All events carry an optional consumer-supplied tag for dispatch routing.
Asset filter (P8)
includesAssetsJson column on WatchedAddress and WatchedCredential. JSON array of {policyId, assetNameHex}. Non-matching txs are skipped (cursor still advances). addWatchedAddress / addWatchedCredential accept the filter.
Public helpers parseAssetFilter, matchesAssetFilter, type AssetFilterEntry.
Coalesce window (P9)
coalesceMs column on WatchedAddress and WatchedCredential (1 – 300_000 ms). Bus events fire at most once per window with cumulative deltas; BlockchainEvent rows persist immediately. Tumbling-window semantics. stopWatcher flushes pending buffers.
Replay API
New action getEventsSince(scope, key, fromBlock?, limit?). scope: 'address' | 'credential' | 'policy'. Returns persisted BlockchainEvent rows ordered by blockHeight ascending. Cursor pagination via fromBlock (exclusive); default limit 1000, hard cap 10_000.
src/ogmios-watcher.ts — per-block filter pass: in-memory watch index (refreshed every 10 s), derives WatchedUtxo / mint / burn shapes from Schema.Block, persists BlockchainEvent rows tagged backend: 'ogmios' with slot, advances WatcherCursor.
src/backfill.ts — Blockfrost-based one-shot history fetch on watch-add under Ogmios mode. Capped at the chainSync cursor's tip. Backfill rows tagged backend: 'blockfrost' so rollback never touches them.
New Event Delivery Contract section in ARCHITECTURE.md — guarantees, non-guarantees, consumer guidance for state-machine handlers, replay patterns, coalesce+replay interaction.
README rewritten ~600 → ~100 lines; full reference content lives in docs/.
QUICKSTART.md, ARCHITECTURE.md, SETUP.md refreshed for the current entity / event / action surface.
Changed
Pagination correctness: getCredentialTxsSince now paginates Koios via PostgREST Range headers (1000-row pages, 100k-row safety cap per poll). Previously silently dropped rows past the first page on busy credentials.
Pagination correctness: fetchPolicyAssetEvents switched from assetsHistory (100-row default) to assetsHistoryAll. Previously truncated mint/burn history on high-velocity policies.
extractUtxoDeltas signature: takes Set<string> of watched addresses (was a single string) so the credential watcher can pass every bech32 derivative at once. Address watchers wrap their single address.
Polling section now describes four independent paths (address, transaction, credential, policy) instead of two.
Fixed
Genesis cursor bug: processAddress no longer treats lastCheckedBlock = 0 or null as "no cursor". Fresh-added watches now actually fire on first poll; block 0 is honored as a real cursor.
fetchAddressTransactions falsy-check fix: if (fromBlock != null ...) instead of if (fromBlock ...) to allow block 0.
Known limitations
Ogmios backend has no utxosSpent detection: Ogmios's inputs are outpoints, not (address + value). The polling backend continues to detect spends; switching to Ogmios is currently output-only.
referenceScriptHash not populated under Ogmios: Ogmios delivers full script body; consumer can hash if needed.
Coalesce buffers not threaded through Ogmios chainSync emits in this release — coalesceMs works under Blockfrost mode only.
cardano.transactionConfirmed event declared in the public type surface but still not emitted; planned alongside Phase 2 follow-up work.
Backfill cap uses getLatestBlock rather than slot→block translation. Rare overlap window with chainSync at the boundary; documented.
CDS Model Auto-Discovery: Plugin's CDS models (schema, admin service) were not loaded by consumer apps. CAP's _link_required_services() runs during env construction before cds-plugin.js loads, so the model array set on cds.env.requires.kinds was never merged into the requires entry. Fixed by setting model directly on cds.env.requires['cardano-watcher'] in addition to the kind registration.
@impl Path Resolution: CardanoWatcherAdminService used a relative @impl path (srv/admin-service) which CAP resolved against the consumer app root instead of the plugin package root, causing Cannot find module errors. Fixed by using the package-qualified path @odatano/watch/srv/admin-service.
Async processingAsync processingcapabilityDoing work outside the request that triggered it, with a guarantee that it eventually happens — deferred jobs, retries, and periodic work. Distinct from messaging, which is about telling other systems.SAP and community, narrow by design
ABAP-PRCABAP-PRCpackageA framework for custom multi-step ABAP processes: a process class declares the states, and the framework runs each document through them and monitors the run.independent, abapFramework for multi-step ABAP processes with monitoringfrom ABAP
Event MeshEvent MeshserviceManaged queues and topics over AMQP, MQTT and a REST gateway, and the bus SAP's own applications publish their business events to.sap official, btpManaged queues and topics over AMQP, MQTT and RESTfrom BTP/BAIP
com.sap.cds:cds-services-bomcom.sap.cds:cds-services-bompackageThe Maven bill of materials for CAP Java, pinning every com.sap.cds module in a release, from the API and core runtime to the Spring Boot starters and the CQN engine, to the same version.sap official, capMaven bill of materials pinning CAP Java module versionsfrom CAP
@cap-js-community/event-queue@cap-js-community/event-queuecds-pluginTransactional processing of asynchronous and periodic events, with instant dispatch over Redis Pub/Sub and load spread across every application instance.community org, capTransactional processing of asynchronous and periodic CAP eventsfrom CAP
@cap-js-community/sap-afc-sdk@cap-js-community/sap-afc-sdkpackageSDK for building SAP Advanced Financial Closing scheduling providers on CDS.community org, capSDK for SAP Advanced Financial Closing scheduling providers on CDSfrom CAP
cds-event-monitoringcds-event-monitoringcds-pluginA CAP plugin that stores every event received on its configured messaging topics in a table, with a Fiori-annotated service to browse them, resend events and drain a dead-message queue.independent, capStores, browses and resends messages a CAP service receivesfrom CAP
@sap/cds@sap/cdspackageThe CAP Node.js runtime, which compiles the CDS model, serves the services declared in it, answers generic requests before any handler runs, and loads every cds-plugin.sap official, capCAP Node.js runtimefrom CAP
cds-natscds-natscds-pluginNATS as a messaging service for the CAP Node.js runtime, the broker behind cds.connect for emit and subscribe, for teams already running NATS rather than Event Mesh or Redis.independent, capNATS messaging service for the CAP Node.js runtimefrom CAP
