@txfence/redis 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @txfence/redis
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial public release — policy engine, intent execution, formal verification, adversarial stress testing, cryptographic provenance chains, temporal rules, and MEV protection across EVM, Solana, and Cosmos
+
+### Patch Changes
+
+- Updated dependencies
+  - @txfence/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Chauhan
+
+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 @@
+# @txfence/redis
+
+Redis-backed `CapLockProvider` for [txfence](https://github.com/AdityaChauhanX07/txfence). Drop-in replacement for `createMemoryCapLockProvider` when multiple agents need to coordinate against the same spending caps across processes or machines.
+
+## Why Redis?
+
+`createMemoryCapLockProvider` from `@txfence/core` is in-process. If two agents each have their own process and both spend against the same cap, the in-memory provider cannot see across processes — race conditions are possible.
+
+`@txfence/redis` uses atomic Lua scripts to make `acquire / commit / release` safe across any number of concurrent agents.
+
+## Installation
+
+```bash
+npm install @txfence/redis @txfence/core ioredis
+```
+
+## Usage
+
+```typescript
+import Redis from 'ioredis'
+import { createRedisCapLockProvider } from '@txfence/redis'
+import { createAgent } from '@txfence/core'
+
+const redis = new Redis(process.env.REDIS_URL!)
+
+const capLockProvider = createRedisCapLockProvider(redis, {
+  caps: [
+    {
+      capId: 'treasury-main',
+      absoluteCap:   { maxAmount: 500_000n, token: 'USDC' },
+      rollingWindow: { windowMs: 3_600_000, maxAmount: 25_000n, token: 'USDC' },
+    },
+  ],
+  keyPrefix: 'txfence:caps',
+})
+
+const agent = createAgent(
+  config, adapters, rpcUrls, executor,
+  capLockProvider,
+)
+```
+
+## Atomicity
+
+Every operation that mutates a cap (`acquire`, `commit`, `release`) runs as a single Lua script inside Redis. The script holds the lock for the duration of the check-and-mutate, so two agents racing for the last 100 USDC of headroom cannot both succeed.
+
+## Connection lifecycle
+
+`@txfence/redis` does not create or close the `Redis` client. Inject your own:
+
+```typescript
+const redis = new Redis(process.env.REDIS_URL!)
+
+// ... use the provider ...
+
+await redis.quit()
+```
+
+Full project README: https://github.com/AdityaChauhanX07/txfence
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Redis } from 'ioredis';
+import { CapConfig, CapLockProvider } from '@txfence/core';
+
+declare function createRedisCapLockProvider(redis: Redis, configs: CapConfig[]): CapLockProvider;
+
+export { createRedisCapLockProvider };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/scripts.ts
+var ACQUIRE_SCRIPT = `
+local absoluteTotal = tonumber(redis.call('GET', KEYS[1])) or 0
+local pendingTotal = tonumber(redis.call('GET', KEYS[2])) or 0
+local amount = tonumber(ARGV[1])
+local absoluteCapMax = tonumber(ARGV[2])
+local rollingWindowMax = tonumber(ARGV[3])
+local rollingWindowMs = tonumber(ARGV[4])
+local currentTime = tonumber(ARGV[6])
+
+if absoluteCapMax > 0 then
+  if absoluteTotal + pendingTotal + amount > absoluteCapMax then
+    return 'absolute_cap_exceeded'
+  end
+end
+
+if rollingWindowMax > 0 then
+  local windowStart = currentTime - rollingWindowMs
+  redis.call('ZREMRANGEBYSCORE', KEYS[4], '-inf', windowStart - 1)
+  local members = redis.call('ZRANGEBYSCORE', KEYS[4], windowStart, '+inf')
+  local windowSum = 0
+  for _, member in ipairs(members) do
+    local sep = string.find(member, ':', 1, true)
+    if sep then
+      windowSum = windowSum + (tonumber(string.sub(member, sep + 1)) or 0)
+    end
+  end
+  if windowSum + pendingTotal + amount > rollingWindowMax then
+    return 'rolling_window_exceeded'
+  end
+end
+
+redis.call('INCRBY', KEYS[2], ARGV[1])
+redis.call('SET', KEYS[3], ARGV[1], 'EX', 300)
+return 'granted'
+`;
+var COMMIT_SCRIPT = `
+local pendingTotal = tonumber(redis.call('GET', KEYS[2])) or 0
+local amount = tonumber(ARGV[1])
+local currentTime = ARGV[3]
+
+if pendingTotal > amount then
+  redis.call('DECRBY', KEYS[2], ARGV[1])
+else
+  redis.call('SET', KEYS[2], 0)
+end
+
+redis.call('INCRBY', KEYS[1], ARGV[1])
+redis.call('ZADD', KEYS[4], currentTime, currentTime .. ':' .. ARGV[1])
+redis.call('DEL', KEYS[3])
+return 'ok'
+`;
+var RELEASE_SCRIPT = `
+local pendingTotal = tonumber(redis.call('GET', KEYS[1])) or 0
+local amount = tonumber(ARGV[1])
+
+if pendingTotal > amount then
+  redis.call('DECRBY', KEYS[1], ARGV[1])
+else
+  redis.call('SET', KEYS[1], 0)
+end
+
+redis.call('DEL', KEYS[2])
+return 'ok'
+`;
+
+// src/provider.ts
+function absoluteKey(capId) {
+  return `txfence:cap:${capId}:absolute`;
+}
+function pendingKey(capId) {
+  return `txfence:cap:${capId}:pending`;
+}
+function lockKey(capId, lockId) {
+  return `txfence:cap:${capId}:lock:${lockId}`;
+}
+function windowKey(capId) {
+  return `txfence:cap:${capId}:window`;
+}
+function generateLockId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function createRedisCapLockProvider(redis, configs) {
+  return {
+    async acquire(capId, amount, _token) {
+      const config = configs.find((c) => c.capId === capId);
+      if (config === void 0) throw new Error("unknown capId: " + capId);
+      const lockId = generateLockId();
+      const absoluteCapMax = (config.absoluteCap?.maxAmount ?? 0n).toString();
+      const rollingWindowMax = (config.rollingWindow?.maxAmount ?? 0n).toString();
+      const rollingWindowMs = (config.rollingWindow?.windowMs ?? 0).toString();
+      const result = await redis.eval(
+        ACQUIRE_SCRIPT,
+        4,
+        absoluteKey(capId),
+        pendingKey(capId),
+        lockKey(capId, lockId),
+        windowKey(capId),
+        amount.toString(),
+        absoluteCapMax,
+        rollingWindowMax,
+        rollingWindowMs,
+        lockId,
+        Date.now().toString()
+      );
+      const resultStr = String(result);
+      if (resultStr === "granted") return { granted: true, lockId };
+      if (resultStr === "absolute_cap_exceeded") return { granted: false, reason: "absolute_cap_exceeded" };
+      if (resultStr === "rolling_window_exceeded") return { granted: false, reason: "rolling_window_exceeded" };
+      throw new Error("unexpected result from Redis acquire script: " + resultStr);
+    },
+    async release(capId, lockId, amount) {
+      await redis.eval(
+        RELEASE_SCRIPT,
+        2,
+        pendingKey(capId),
+        lockKey(capId, lockId),
+        amount.toString()
+      );
+    },
+    async commit(capId, lockId, amount) {
+      await redis.eval(
+        COMMIT_SCRIPT,
+        4,
+        absoluteKey(capId),
+        pendingKey(capId),
+        lockKey(capId, lockId),
+        windowKey(capId),
+        amount.toString(),
+        lockId,
+        Date.now().toString()
+      );
+    }
+  };
+}
+export {
+  createRedisCapLockProvider
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@txfence/redis",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "ioredis": "^5.3.2",
+    "@txfence/core": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}