@mnemopay/sdk 0.7.4 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +266 -193
- package/dist/fraud.d.ts +75 -1
- package/dist/fraud.d.ts.map +1 -1
- package/dist/fraud.js +247 -26
- package/dist/fraud.js.map +1 -1
- package/dist/identity.d.ts +154 -0
- package/dist/identity.d.ts.map +1 -0
- package/dist/identity.js +277 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.d.ts +29 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +87 -7
- package/dist/index.js.map +1 -1
- package/dist/ledger.d.ts +137 -0
- package/dist/ledger.d.ts.map +1 -0
- package/dist/ledger.js +250 -0
- package/dist/ledger.js.map +1 -0
- package/dist/network.d.ts +155 -0
- package/dist/network.d.ts.map +1 -0
- package/dist/network.js +263 -0
- package/dist/network.js.map +1 -0
- package/dist/rails/index.d.ts +2 -0
- package/dist/rails/index.d.ts.map +1 -1
- package/dist/rails/index.js +5 -1
- package/dist/rails/index.js.map +1 -1
- package/dist/rails/paystack.d.ts +157 -0
- package/dist/rails/paystack.d.ts.map +1 -0
- package/dist/rails/paystack.js +366 -0
- package/dist/rails/paystack.js.map +1 -0
- package/package.json +23 -10
package/README.md
CHANGED
|
@@ -1,193 +1,266 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
**Give
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
###
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
const
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
await
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
1
|
+
# MnemoPay
|
|
2
|
+
|
|
3
|
+
**Give your AI agents real superpowers.** Memory + Payments + Identity in one SDK.
|
|
4
|
+
|
|
5
|
+
Your agent remembers every interaction, handles real money, builds reputation, and trades with other agents — all with a balanced double-entry ledger that never drifts by a penny.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @mnemopay/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import MnemoPay from "@mnemopay/sdk";
|
|
13
|
+
|
|
14
|
+
const agent = MnemoPay.quick("my-agent");
|
|
15
|
+
|
|
16
|
+
await agent.remember("User prefers monthly billing");
|
|
17
|
+
const tx = await agent.charge(25, "Monthly API access");
|
|
18
|
+
await agent.settle(tx.id);
|
|
19
|
+
// Agent now has memory, money, and reputation. Ledger balanced.
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
330+ tests. Production-hardened. MIT licensed.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Why MnemoPay
|
|
27
|
+
|
|
28
|
+
AI agents can think. They can't remember or pay. MnemoPay fixes both.
|
|
29
|
+
|
|
30
|
+
| Problem | Without MnemoPay | With MnemoPay |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Memory | Every session starts cold | Agent remembers everything — decays naturally, strengthens on use |
|
|
33
|
+
| Payments | Manual API calls, no escrow | Charge → escrow → settle → refund. Real money, real rails |
|
|
34
|
+
| Identity | No agent verification | KYA (Know Your Agent) with capability tokens and permissions |
|
|
35
|
+
| Trust | No reputation system | Agent FICO score that grows with successful transactions |
|
|
36
|
+
| Accounting | Hope the numbers are right | Double-entry ledger. Every debit has a credit. Always balances to zero |
|
|
37
|
+
| Fraud | Build your own | Velocity checks, anomaly detection, geo-enhanced risk scoring |
|
|
38
|
+
| Multi-agent | Not possible | `net.transact("buyer", "seller", 25, "API access")` — both agents remember |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Features
|
|
43
|
+
|
|
44
|
+
### Memory (Neuroscience-backed)
|
|
45
|
+
- **Ebbinghaus forgetting curve** — memories decay over time, just like the brain
|
|
46
|
+
- **Hebbian reinforcement** — successful transactions strengthen associated memories
|
|
47
|
+
- **Consolidation** — auto-prunes weak memories, keeps what matters
|
|
48
|
+
- **Semantic recall** — find memories by relevance, not just recency
|
|
49
|
+
- **100KB per memory** — store rich context, not just strings
|
|
50
|
+
|
|
51
|
+
### Payments (Bank-grade math)
|
|
52
|
+
- **Double-entry bookkeeping** — Luca Pacioli's 1494 system, 330+ tests proving it works
|
|
53
|
+
- **Escrow flow** — charge → hold → settle → refund (same as Stripe/Square)
|
|
54
|
+
- **Platform fee** — 1.9% on settlement (configurable, volume-tiered: 1.9% → 1.5% → 1.0%)
|
|
55
|
+
- **3 payment rails** — Paystack (Africa), Stripe (global), Lightning (BTC)
|
|
56
|
+
- **Penny-precise** — stress-tested with 1,000 random transactions, fee + net = gross every time
|
|
57
|
+
|
|
58
|
+
### Identity (KYA Compliance)
|
|
59
|
+
- **Agent identity** — cryptographic keypairs, owner verification
|
|
60
|
+
- **Capability tokens** — scoped permissions (charge, settle, refund, remember)
|
|
61
|
+
- **Spend limits** — max per transaction, max total spend, counterparty whitelists
|
|
62
|
+
- **Kill switch** — revoke all tokens instantly
|
|
63
|
+
|
|
64
|
+
### Fraud Detection (Geo-enhanced)
|
|
65
|
+
- **Velocity checks** — per-minute, per-hour, per-day limits
|
|
66
|
+
- **Anomaly detection** — z-score + optional ML (Isolation Forest)
|
|
67
|
+
- **Geo-enhanced** — country tracking, rapid-hop detection, currency mismatch, timezone anomalies
|
|
68
|
+
- **Geo trust** — consistent location builds trust, dampens false positives
|
|
69
|
+
- **OFAC sanctions** — hard blocks for sanctioned countries (KP, IR, SY, CU, RU)
|
|
70
|
+
- **Behavioral fingerprinting** — detects drift from agent's normal patterns
|
|
71
|
+
|
|
72
|
+
### Multi-Agent Commerce
|
|
73
|
+
- **MnemoPayNetwork** — register agents, execute deals, shared memory context
|
|
74
|
+
- **One method** — `net.transact(buyer, seller, amount, reason)` handles everything
|
|
75
|
+
- **Both remember** — buyer and seller each store the deal in their memory
|
|
76
|
+
- **Supply chains** — 10-step agent chains, 100-agent marketplaces, all tested
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Payment Rails
|
|
81
|
+
|
|
82
|
+
MnemoPay supports real money movement through pluggable payment rails:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { PaystackRail, StripeRail, LightningRail } from "@mnemopay/sdk";
|
|
86
|
+
|
|
87
|
+
// Africa (NGN, GHS, ZAR, KES)
|
|
88
|
+
const paystack = new PaystackRail(process.env.PAYSTACK_SECRET_KEY!);
|
|
89
|
+
|
|
90
|
+
// Global (USD, EUR, GBP — cards)
|
|
91
|
+
const stripe = new StripeRail(process.env.STRIPE_SECRET_KEY!);
|
|
92
|
+
|
|
93
|
+
// Crypto (BTC via Lightning Network)
|
|
94
|
+
const lightning = new LightningRail(LND_URL, MACAROON);
|
|
95
|
+
|
|
96
|
+
// Plug into any agent
|
|
97
|
+
const agent = MnemoPay.quick("my-agent", { paymentRail: paystack });
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Paystack Rail (Built for Africa)
|
|
101
|
+
- Initialize → checkout → verify flow
|
|
102
|
+
- Charge saved cards (authorization codes)
|
|
103
|
+
- Bank transfers / payouts
|
|
104
|
+
- Webhook HMAC-SHA512 verification
|
|
105
|
+
- Bank account resolution
|
|
106
|
+
- 23 Nigerian banks pre-mapped
|
|
107
|
+
|
|
108
|
+
### Fee Structure
|
|
109
|
+
|
|
110
|
+
| Tier | Monthly Volume | Platform Fee |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| Standard | < $10,000 | 1.9% |
|
|
113
|
+
| Growth | $10,000 - $100,000 | 1.5% |
|
|
114
|
+
| Scale | $100,000+ | 1.0% |
|
|
115
|
+
|
|
116
|
+
Fees are automatically tiered based on cumulative settled volume per agent.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## MCP Server
|
|
121
|
+
|
|
122
|
+
MnemoPay runs as an MCP server, giving Claude and other AI assistants direct access:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npx @mnemopay/sdk init
|
|
126
|
+
# or
|
|
127
|
+
claude mcp add mnemopay -s user -- npx -y @mnemopay/sdk
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Available tools: `charge`, `settle`, `refund`, `remember`, `recall`, `balance`, `history`, `profile`, `reputation`, `fraud_stats`, `dispute`, `reinforce`, `consolidate`, `forget`, `logs`.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Middleware
|
|
135
|
+
|
|
136
|
+
Drop MnemoPay into your existing AI stack:
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
// OpenAI
|
|
140
|
+
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/openai";
|
|
141
|
+
|
|
142
|
+
// Anthropic
|
|
143
|
+
import { mnemoPayMiddleware } from "@mnemopay/sdk/middleware/anthropic";
|
|
144
|
+
|
|
145
|
+
// LangGraph
|
|
146
|
+
import { mnemoPayTools } from "@mnemopay/sdk/langgraph";
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Multi-Agent Example
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
import { MnemoPayNetwork } from "@mnemopay/sdk";
|
|
155
|
+
|
|
156
|
+
const net = new MnemoPayNetwork({ fraud: { platformFeeRate: 0.019 } });
|
|
157
|
+
|
|
158
|
+
// Register agents
|
|
159
|
+
net.register("buyer-bot", "owner-1", "dev@company.com");
|
|
160
|
+
net.register("seller-bot", "owner-2", "dev@company.com");
|
|
161
|
+
|
|
162
|
+
// Execute a deal — both agents remember, seller gets paid, ledger balances
|
|
163
|
+
const deal = await net.transact("buyer-bot", "seller-bot", 25, "API access for 1 month");
|
|
164
|
+
|
|
165
|
+
console.log(deal.netAmount); // 24.52 (after 1.9% fee)
|
|
166
|
+
console.log(deal.platformFee); // 0.48
|
|
167
|
+
console.log(deal.buyerMemoryId); // buyer remembers the purchase
|
|
168
|
+
console.log(deal.sellerMemoryId);// seller remembers the sale
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Architecture
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
┌─────────────────────────────────────────────────┐
|
|
177
|
+
│ MnemoPay SDK │
|
|
178
|
+
├──────────┬──────────┬───────────┬───────────────┤
|
|
179
|
+
│ Memory │ Payments │ Identity │ Fraud Guard │
|
|
180
|
+
│ │ │ │ │
|
|
181
|
+
│ remember │ charge │ KYA │ velocity │
|
|
182
|
+
│ recall │ settle │ tokens │ anomaly │
|
|
183
|
+
│ reinforce│ refund │ perms │ geo-enhanced │
|
|
184
|
+
│ forget │ dispute │ killswitch│ ML (optional) │
|
|
185
|
+
├──────────┴──────────┴───────────┴───────────────┤
|
|
186
|
+
│ Double-Entry Ledger │
|
|
187
|
+
│ debit + credit = always zero │
|
|
188
|
+
├─────────────────────────────────────────────────┤
|
|
189
|
+
│ Payment Rails │
|
|
190
|
+
│ Paystack │ Stripe │ Lightning │
|
|
191
|
+
└─────────────────────────────────────────────────┘
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Persistence
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
// File-based (default)
|
|
200
|
+
const agent = MnemoPay.quick("my-agent", { persistDir: "./data" });
|
|
201
|
+
|
|
202
|
+
// SQLite (production)
|
|
203
|
+
import { SQLiteStorage } from "@mnemopay/sdk/storage";
|
|
204
|
+
const storage = new SQLiteStorage("./mnemopay.db");
|
|
205
|
+
|
|
206
|
+
// Everything persists: memories, transactions, identity, fraud state, geo profiles
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## API Reference
|
|
212
|
+
|
|
213
|
+
### Core Methods
|
|
214
|
+
|
|
215
|
+
| Method | Description |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `agent.remember(content, opts?)` | Store a memory with importance scoring |
|
|
218
|
+
| `agent.recall(limit?, query?)` | Retrieve memories by relevance |
|
|
219
|
+
| `agent.charge(amount, reason)` | Create an escrow hold |
|
|
220
|
+
| `agent.settle(txId, counterpartyId?)` | Release escrow, apply fee, complete payment |
|
|
221
|
+
| `agent.refund(txId)` | Reverse a completed or pending transaction |
|
|
222
|
+
| `agent.dispute(txId, reason)` | File a dispute against a settled transaction |
|
|
223
|
+
| `agent.balance()` | Get wallet balance and reputation |
|
|
224
|
+
| `agent.verifyLedger()` | Confirm double-entry ledger balances to zero |
|
|
225
|
+
| `agent.history(limit?)` | Get transaction history |
|
|
226
|
+
| `agent.consolidate()` | Prune stale memories |
|
|
227
|
+
|
|
228
|
+
### Network Methods
|
|
229
|
+
|
|
230
|
+
| Method | Description |
|
|
231
|
+
|---|---|
|
|
232
|
+
| `net.register(agentId, ownerId, email)` | Register an agent on the network |
|
|
233
|
+
| `net.transact(buyer, seller, amount, reason)` | Full deal: charge → settle → memory → identity |
|
|
234
|
+
| `net.refundDeal(dealId)` | Reverse a deal, both agents remember the refund |
|
|
235
|
+
| `net.stats()` | Network-wide statistics |
|
|
236
|
+
| `net.dealsBetween(agentA, agentB)` | Get deal history between two agents |
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## Testing
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
npm test # Run all 330+ tests
|
|
244
|
+
npm run lint # Type check
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Test coverage:
|
|
248
|
+
- `core.test.ts` — 67 tests (memory, payments, lifecycle)
|
|
249
|
+
- `fraud.test.ts` — 43 tests (velocity, anomaly, fees, disputes)
|
|
250
|
+
- `geo-fraud.test.ts` — 20 tests (geo signals, trust, sanctions)
|
|
251
|
+
- `identity.test.ts` — 44 tests (KYA, tokens, permissions)
|
|
252
|
+
- `ledger.test.ts` — 21 tests (double-entry, reconciliation)
|
|
253
|
+
- `network.test.ts` — 22 tests (multi-agent, deals, supply chains)
|
|
254
|
+
- `paystack.test.ts` — 46 tests (rail, webhooks, transfers)
|
|
255
|
+
- `stress.test.ts` — 32 tests (1000-cycle precision, parallel ops)
|
|
256
|
+
- `recall.test.ts` — 35 tests (semantic search, decay, reinforcement)
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## License
|
|
261
|
+
|
|
262
|
+
MIT
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
Built by [Jerry Omiagbo](https://github.com/mnemopay)
|
package/dist/fraud.d.ts
CHANGED
|
@@ -7,9 +7,17 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { IsolationForest, TransactionGraph, BehaviorProfile } from "./fraud-ml.js";
|
|
9
9
|
import type { CollusionSignal, BehaviorSnapshot } from "./fraud-ml.js";
|
|
10
|
+
export interface FeeTier {
|
|
11
|
+
/** Minimum cumulative settled volume (USD) to qualify */
|
|
12
|
+
minVolume: number;
|
|
13
|
+
/** Fee rate for this tier */
|
|
14
|
+
rate: number;
|
|
15
|
+
}
|
|
10
16
|
export interface FraudConfig {
|
|
11
|
-
/** Platform fee rate on settle (0.
|
|
17
|
+
/** Platform fee rate on settle (0.019 = 1.9%). Default 0.019. Used when no tiers match. */
|
|
12
18
|
platformFeeRate: number;
|
|
19
|
+
/** Volume-based fee tiers (sorted by minVolume ascending). Overrides platformFeeRate when agent qualifies. */
|
|
20
|
+
feeTiers: FeeTier[];
|
|
13
21
|
/** Max charges per minute per agent. Default 5 */
|
|
14
22
|
maxChargesPerMinute: number;
|
|
15
23
|
/** Max charges per hour per agent. Default 30 */
|
|
@@ -38,6 +46,8 @@ export interface FraudConfig {
|
|
|
38
46
|
blockedCountries: string[];
|
|
39
47
|
/** Enable ML fraud detection (Isolation Forest, graph analysis, behavioral fingerprinting). Default false */
|
|
40
48
|
ml: boolean;
|
|
49
|
+
/** Geo-enhanced fraud detection config */
|
|
50
|
+
geo: GeoFraudConfig;
|
|
41
51
|
}
|
|
42
52
|
export declare const DEFAULT_FRAUD_CONFIG: FraudConfig;
|
|
43
53
|
export interface FraudSignal {
|
|
@@ -86,6 +96,40 @@ export interface RequestContext {
|
|
|
86
96
|
country?: string;
|
|
87
97
|
userAgent?: string;
|
|
88
98
|
sessionId?: string;
|
|
99
|
+
/** UTC offset in hours (e.g., +1 for WAT, -5 for CDT) */
|
|
100
|
+
utcOffset?: number;
|
|
101
|
+
/** Currency code associated with this request's region */
|
|
102
|
+
currency?: string;
|
|
103
|
+
}
|
|
104
|
+
/** Per-agent geographic behavior profile */
|
|
105
|
+
export interface GeoProfile {
|
|
106
|
+
/** First country seen — established as "home" after 5+ transactions */
|
|
107
|
+
homeCountry?: string;
|
|
108
|
+
/** All countries seen, with transaction counts */
|
|
109
|
+
countryCounts: Record<string, number>;
|
|
110
|
+
/** Country of last transaction */
|
|
111
|
+
lastCountry?: string;
|
|
112
|
+
/** Timestamps of country changes (for rapid-hop detection) */
|
|
113
|
+
countryChanges: number[];
|
|
114
|
+
/** Total transactions tracked for this profile */
|
|
115
|
+
totalTxCount: number;
|
|
116
|
+
/** Geo trust score 0-1 (higher = more consistent location = less suspicious) */
|
|
117
|
+
trustScore: number;
|
|
118
|
+
}
|
|
119
|
+
/** Geo-specific fraud config. All thresholds designed to FLAG, not BLOCK. */
|
|
120
|
+
export interface GeoFraudConfig {
|
|
121
|
+
/** Enable geo-enhanced fraud signals. Default: true */
|
|
122
|
+
enabled: boolean;
|
|
123
|
+
/** Min transactions before establishing home country. Default: 5 */
|
|
124
|
+
homeCountryThreshold: number;
|
|
125
|
+
/** Country changes in 24h to trigger rapid-hop signal. Default: 3 */
|
|
126
|
+
rapidHopThreshold: number;
|
|
127
|
+
/** High-risk country corridors (pairs). Default: common AML corridors */
|
|
128
|
+
highRiskCorridors: [string, string][];
|
|
129
|
+
/** OFAC/sanctions blocked countries. These BLOCK, not just flag. */
|
|
130
|
+
sanctionedCountries: string[];
|
|
131
|
+
/** Currency-to-country region map for mismatch detection */
|
|
132
|
+
currencyRegions: Record<string, string[]>;
|
|
89
133
|
}
|
|
90
134
|
export declare class FraudGuard {
|
|
91
135
|
readonly config: FraudConfig;
|
|
@@ -99,12 +143,16 @@ export declare class FraudGuard {
|
|
|
99
143
|
private feeLedger;
|
|
100
144
|
/** Total platform fees collected */
|
|
101
145
|
private _platformFeesCollected;
|
|
146
|
+
/** Cumulative settled volume per agent (for tiered pricing) */
|
|
147
|
+
private agentSettledVolume;
|
|
102
148
|
/** Known IPs per agent for consistency checks */
|
|
103
149
|
private agentIps;
|
|
104
150
|
/** Flagged agents (soft block — allowed but monitored) */
|
|
105
151
|
private flaggedAgents;
|
|
106
152
|
/** Hard-blocked agents */
|
|
107
153
|
private blockedAgents;
|
|
154
|
+
/** Per-agent geo behavior profiles */
|
|
155
|
+
private geoProfiles;
|
|
108
156
|
/** ML anomaly detection — only loaded when ml: true */
|
|
109
157
|
readonly isolationForest: IsolationForest | null;
|
|
110
158
|
/** Transaction graph — only loaded when ml: true */
|
|
@@ -130,8 +178,18 @@ export declare class FraudGuard {
|
|
|
130
178
|
detectCollusion(): CollusionSignal[];
|
|
131
179
|
/** Get an agent's behavioral baseline (requires ml: true) */
|
|
132
180
|
getAgentBaseline(agentId: string): BehaviorSnapshot | undefined;
|
|
181
|
+
/**
|
|
182
|
+
* Get the effective fee rate for an agent based on cumulative settled volume.
|
|
183
|
+
* Higher volume = lower fees (loyalty reward for active agents).
|
|
184
|
+
*/
|
|
185
|
+
getEffectiveFeeRate(agentId: string): number;
|
|
186
|
+
/**
|
|
187
|
+
* Get an agent's cumulative settled volume.
|
|
188
|
+
*/
|
|
189
|
+
getAgentVolume(agentId: string): number;
|
|
133
190
|
/**
|
|
134
191
|
* Calculate and record platform fee for a settlement.
|
|
192
|
+
* Uses volume-based tiered pricing when configured.
|
|
135
193
|
* Returns { grossAmount, feeAmount, netAmount }.
|
|
136
194
|
*/
|
|
137
195
|
applyPlatformFee(txId: string, agentId: string, grossAmount: number): PlatformFeeRecord;
|
|
@@ -176,6 +234,22 @@ export declare class FraudGuard {
|
|
|
176
234
|
openDisputes: number;
|
|
177
235
|
platformFeesCollected: number;
|
|
178
236
|
};
|
|
237
|
+
/**
|
|
238
|
+
* Assess geo-related risk signals for a transaction.
|
|
239
|
+
* Design: all signals are LOW weight (0.1-0.35) so they NEVER block alone.
|
|
240
|
+
* Only sanctioned countries use critical weight (0.9).
|
|
241
|
+
* Agents build geo trust over time, dampening signals further.
|
|
242
|
+
*/
|
|
243
|
+
private assessGeo;
|
|
244
|
+
/**
|
|
245
|
+
* Update geo profile after a successful charge.
|
|
246
|
+
* Builds geo trust over time — consistent location = higher trust.
|
|
247
|
+
*/
|
|
248
|
+
updateGeoProfile(agentId: string, ctx?: RequestContext): void;
|
|
249
|
+
/** Get or create a geo profile for an agent */
|
|
250
|
+
private getOrCreateGeoProfile;
|
|
251
|
+
/** Get an agent's geo profile (for diagnostics/display) */
|
|
252
|
+
getGeoProfile(agentId: string): GeoProfile | undefined;
|
|
179
253
|
serialize(): string;
|
|
180
254
|
static deserialize(json: string, config?: Partial<FraudConfig>): FraudGuard;
|
|
181
255
|
}
|
package/dist/fraud.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"fraud.d.ts","sourceRoot":"","sources":["../src/fraud.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAe,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIpF,MAAM,WAAW,WAAW;IAC1B,
|
|
1
|
+
{"version":3,"file":"fraud.d.ts","sourceRoot":"","sources":["../src/fraud.ts"],"names":[],"mappings":"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"}
|