@shroud-fi/compliance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShroudFi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @shroud-fi/compliance
+
+> Operator-side viewing-key tools. Audit trails without spend authority.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/compliance.svg)](https://www.npmjs.com/package/@shroud-fi/compliance)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/compliance
+```
+
+## What it does
+
+`@shroud-fi/compliance` lets the operator behind an agent generate an **audit trail** of every payment ever directed at the agent's meta-address — without giving the auditor spend authority and without revealing live strategy.
+
+The mechanism is the scan key. In ShroudFi, the spending key controls funds; the scanning key only *sees* payments. Exporting a scan-only viewing key gives an auditor full historical visibility into receipts while keeping the spend authority sealed.
+
+## Why it matters
+
+Confidentiality infrastructure for AI agents has to coexist with compliance. ShroudFi is **not** an anonymizer — it's a directed-payment system (like a PO box) where the recipient can selectively prove receipt to a third party. This package is how you do that.
+
+## Quick start
+
+```ts
+import { exportViewingKey, replayHistory } from '@shroud-fi/compliance';
+import { deriveAgentIdentity } from '@shroud-fi/core';
+import { createTransport } from '@shroud-fi/transport';
+
+const identity = deriveAgentIdentity(masterSeed);
+const viewingKey = exportViewingKey(identity);
+// Hand `viewingKey` to your auditor — they cannot spend.
+
+// Auditor replays history:
+const transport = createTransport({ chain: 'base', rpcUrl });
+const history = await replayHistory(transport, viewingKey, {
+  fromBlock: 46_800_000n,
+  toBlock: 'latest',
+});
+
+// history: every payment ever sent to the meta-address, with block + tx context.
+```
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `exportViewingKey(identity)` | Serialize a scan-only key safe to hand to an auditor. |
+| `replayHistory(transport, viewingKey, range)` | Reconstruct every payment ever sent to the meta-address. |
+| `ViewingKeyExport` | Serializable type, safe to log + store. Does not contain spending authority. |
+
+Full API reference: [shroudfi.live/sdk#compliance](https://shroudfi.live/sdk#compliance)
+
+## Privacy invariants
+
+- **No backdoor.** Viewing keys are agent-opt-in and agent-generated. There's no global auditor key and no contract-level disclosure mechanism.
+- **Scoped.** A viewing key gives one-way visibility to inbound payments to one agent. It does not expose outbound payments the agent sent.
+- **Revocable in practice.** Since the viewing key only enables reading historical announcements, an agent rotating its meta-address effectively cuts off future visibility for old viewing-key holders.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export type { ViewingKeyConfig, AuditTrail, DisclosureProof } from './types.js';
+export declare function generateViewingKey(_config: import('./types.js').ViewingKeyConfig): Promise<import('./types.js').DisclosureProof>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,YAAY,EAAE,gBAAgB,GAC7C,OAAO,CAAC,OAAO,YAAY,EAAE,eAAe,CAAC,CAE/C"}

package/dist/cjs/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateViewingKey = generateViewingKey;
+function generateViewingKey(_config) {
+    throw new Error('Not implemented');
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;AAEA,gDAIC;AAJD,SAAgB,kBAAkB,CAChC,OAA8C;IAE9C,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;AACrC,CAAC"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,19 @@
+import type { Address } from 'viem';
+export interface ViewingKeyConfig {
+    readonly spendingPrivateKey: `0x${string}`;
+    readonly chain: 'base' | 'baseSepolia';
+}
+export interface AuditTrail {
+    readonly stealthAddress: Address;
+    readonly ephemeralPubKey: `0x${string}`;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+    readonly timestamp: number;
+}
+export interface DisclosureProof {
+    readonly viewingPublicKey: `0x${string}`;
+    readonly spendingPublicKey: `0x${string}`;
+    readonly stealthMetaAddress: string;
+    readonly auditTrail: readonly AuditTrail[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,KAAK,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,KAAK,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;CAC5C"}

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export type { ViewingKeyConfig, AuditTrail, DisclosureProof } from './types.js';
+export declare function generateViewingKey(_config: import('./types.js').ViewingKeyConfig): Promise<import('./types.js').DisclosureProof>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,YAAY,EAAE,gBAAgB,GAC7C,OAAO,CAAC,OAAO,YAAY,EAAE,eAAe,CAAC,CAE/C"}

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export function generateViewingKey(_config) {
+    throw new Error('Not implemented');
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB,CAChC,OAA8C;IAE9C,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;AACrC,CAAC"}

package/dist/esm/types.d.ts

@@ -0,0 +1,19 @@
+import type { Address } from 'viem';
+export interface ViewingKeyConfig {
+    readonly spendingPrivateKey: `0x${string}`;
+    readonly chain: 'base' | 'baseSepolia';
+}
+export interface AuditTrail {
+    readonly stealthAddress: Address;
+    readonly ephemeralPubKey: `0x${string}`;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+    readonly timestamp: number;
+}
+export interface DisclosureProof {
+    readonly viewingPublicKey: `0x${string}`;
+    readonly spendingPublicKey: `0x${string}`;
+    readonly stealthMetaAddress: string;
+    readonly auditTrail: readonly AuditTrail[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,KAAK,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,KAAK,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;CAC5C"}

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}