@decentrys/sentinel-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,10 @@
 # @decentrys/sentinel-sdk
 
-Monitoring for deployed contracts, wallets and treasuries.
+**Watches contracts, wallets and treasuries you already deployed, and tells you when something changes.**
+
+An audit is a point-in-time review. Sentinel is what happens afterwards: you
+register what you own, write rules about what would worry you, and get alerts
+when those conditions actually occur.
 
 ## Install
 
@@ -8,46 +12,128 @@ Monitoring for deployed contracts, wallets and treasuries.
 npm install @decentrys/sentinel-sdk
 ```
 
-## Use
+## Getting an API key
+
+Sign in at [decentrys.com/developers](https://decentrys.com/developers) and create a key.
+
+There are two kinds, and picking the wrong one is the mistake that matters:
+
+| Prefix | Where it belongs | Why |
+|---|---|---|
+| `dk_pub_live_…` | **Publishable.** Ships inside a wallet, extension or mobile app. | Bounded to the origins you register and to read-only Protect endpoints. Anyone can extract it from your bundle; that's expected, and it's why it can't do anything dangerous. |
+| `dk_live_…` | **Secret.** Server-side only. | Full scope access. If this ends up in a client bundle it is a leaked credential the moment it ships. |
+
+**Sentinel needs a secret key.** A publishable key is refused at construction —
+configuring detection is not something a credential shipped inside a client may do.
+
+## Quick start
 
 ```ts
-import { Sentinel, rulesFromAudit } from '@decentrys/sentinel-sdk';
+import { Sentinel } from '@decentrys/sentinel-sdk';
 
 const sentinel = new Sentinel({ apiKey: 'dk_live_...' });
 
-await sentinel.registerContract({ projectId, chain: 'ethereum', address });
+// 1. What do you want watched?
+await sentinel.registerContract({ projectId, chain: 'ethereum', address: '0xabc...', label: 'Vault v2' });
+await sentinel.registerTreasury({ projectId, chain: 'ethereum', address: '0xdef...' });
+
+// 2. What would worry you?
+await sentinel.createRule({
+  projectId,
+  name: 'Large treasury outflow',
+  severity: 'HIGH',
+  triggerType: 'treasury.transfer',
+  conditions: {
+    op: 'AND',
+    conditions: [
+      { op: 'eq', field: 'transfer.direction', value: 'OUT' },
+      { op: 'gt', field: 'transfer.valueUsd', value: 50000 },
+    ],
+  },
+  actions: [{ type: 'ALERT', config: {} }, { type: 'SLACK', config: { webhookUrl } }],
+  cooldownSeconds: 300,
+});
+
+// 3. Read what fired
+const { data: alerts } = await sentinel.listAlerts({ status: 'NEW' });
+await sentinel.acknowledgeAlert(alerts[0].id, 'Expected — scheduled rebalance.');
+```
+
+`await sentinel.catalog()` returns every fact field, operator and action you can
+build a rule from, so you can generate a rule builder rather than hardcode one.
+
+## Test a rule before you arm it
+
+```ts
+const result = await sentinel.testRule(ruleId, { 'transfer.direction': 'OUT', 'transfer.valueUsd': 75000 });
+// result.matched -> true, with the comparison that decided it
+```
+
+A rule nobody has tested is a rule whose behaviour you'll discover during an
+incident.
+
+## Report events we can't see
+
+Some things only your system knows: a deploy pipeline running, an internally
+approved treasury movement, an off-chain governance action.
 
-// Turn what an audit learned into what the system watches.
-for (const { rule } of rulesFromAudit({ projectId, capabilities })) {
+```ts
+await sentinel.reportEvent({ projectId, eventName: 'governance.executed', chain: 'ethereum', txHash, facts: {...} });
+```
+
+**This is the one method that never throws.** It runs on your hot path, and a
+monitoring call must not be able to fail the thing it's monitoring. It returns
+a boolean instead.
+
+## Turn an audit into monitoring
+
+The most valuable thing here. An audit identifies what a contract can do; this
+converts that into what gets watched.
+
+```ts
+import { rulesFromAudit, unmappedCapabilities } from '@decentrys/sentinel-sdk';
+
+const capabilities = [{ type: 'UPGRADEABLE', grantedBy: 'EIP1967' }, { type: 'MINT_AUTHORITY' }];
+
+for (const { rule } of rulesFromAudit({ projectId, capabilities, treasuryThresholdUsd: 50000 })) {
   await sentinel.createRule(rule);
 }
+
+// Told, not hidden: which capabilities produced no rule.
+console.log(unmappedCapabilities(capabilities));
 ```
 
-## It throws, deliberately
+It watches the upgrade **happening**, never the contract **being** upgradeable —
+a capability is not a fault. Capabilities with no plausible response generate no
+rule, because a rule nobody can act on trains a team to close alerts unread.
 
-Unlike `@decentrys/protect`, this client raises errors. It is management —
-registering a contract, writing a rule. Swallowing a failure would leave an
-operator believing they are monitored when they are not, which is the more
-dangerous silence.
+## It throws
 
-`reportEvent()` is the exception: it runs on your hot path and returns a
-boolean, because a monitoring call must not be able to fail the thing it is
-monitoring.
+Unlike `@decentrys/protect`, this client raises errors. It's management — if
+registering a contract fails, you must know, or you'll believe you're monitored
+when you aren't.
 
-## Audit handover
+```ts
+try {
+  await sentinel.registerContract({ ... });
+} catch (e) {
+  if (e instanceof SentinelError) console.error(e.status, e.message);
+}
+```
 
-`rulesFromAudit()` watches the upgrade *happening*, never the contract *being*
-upgradeable. A capability is not a fault. Capabilities with no plausible
-response generate no rule, and `unmappedCapabilities()` tells you which — a
-rule nobody can act on trains a team to close alerts unread.
+## The rest of the SDK
 
-**Secret keys only.** A publishable key is refused at construction.
+| Package | For |
+|---|---|
+| [`@decentrys/protect`](https://www.npmjs.com/package/@decentrys/protect) | Pre-sign risk assessment for wallets and dapps |
+| [`@decentrys/ui-sdk`](https://www.npmjs.com/package/@decentrys/ui-sdk) | React components that render Protect results |
+| [`@decentrys/sentinel-sdk`](https://www.npmjs.com/package/@decentrys/sentinel-sdk) | Monitoring deployed contracts and treasuries |
+| [`@decentrys/risk-sdk`](https://www.npmjs.com/package/@decentrys/risk-sdk) | Screening for exchanges and custodians |
+| [`@decentrys/dri-sdk`](https://www.npmjs.com/package/@decentrys/dri-sdk) | Fund tracing and recovery intelligence |
+| [`@decentrys/agent`](https://www.npmjs.com/package/@decentrys/agent) | Policy enforcement for autonomous agents |
 
 ## Licence
 
 MIT © Decentrys Labs
 
-## Links
-
-- [decentrys.com](https://decentrys.com) · [SDK overview](https://decentrys.com/sdk) · [Developer API](https://decentrys.com/developers)
-- Source: [github.com/teamdecentrys-byte/Decentrys](https://github.com/teamdecentrys-byte/Decentrys)
+[decentrys.com](https://decentrys.com) · [SDK overview](https://decentrys.com/sdk) · [Developer API](https://decentrys.com/developers) · [Source](https://github.com/teamdecentrys-byte/Decentrys)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentrys/sentinel-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Monitoring for deployed contracts, wallets and treasuries: targets, detection rules, alerts, and audit-to-monitoring handover.",
   "license": "MIT",
   "author": "Decentrys Labs",