@cryptoslip/mcp 0.0.0-stage → 1.0.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NARA Protocol & CryptoSLIP Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # `@cryptoslip/mcp` — PocketSlip MCP Server for Autonomous Agents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Non-custodial Model Context Protocol (MCP) server for **CryptoSLIP Protocol V3.2** (`v33`: `0x3f80aa68Fb4834d6E119EE1cf932C14419Cf63EB`) on **Base Mainnet (`8453`)**.
4
+
5
+ Instead of handing an LLM standing authority over a master private key, hand it a bounded `$5.00 USDC` (`ETH`, `cbBTC`, or `NARA`) `#` Slip URL via `CRYPTOSLIP_URL`.
6
+
7
+ ## Security Architecture
8
+
9
+ - **`V-01` `<1s` Boot Auto-Keep Rotation:** On startup (`bootAndRotate()`), if the slip is unrotated (`nonces == 0`), `PocketSlipVault` immediately executes an on-chain `Keep` (`0%` protocol fee), rotating `claimSigner` to a fresh local key persisted with `0600` permissions. The original `.env` link is invalidated on-chain, bounding prompt-injection risk strictly to that single slip.
10
+ - **`V-02` Out-of-Context `BoundedAgentPolicy` Firewall:** Deterministically enforces `maxPerCallUsdMicro`, `maxSpendsPerMinute`, `maxDailyUsdMicro`, `assertSafeDestination` (blocking burn addresses, token contracts, vaults, routers, and known public test addresses), optional recipient/domain allowlists, `redactSecretsFromToolOutput`, and `100%` Uniswap V4 `NARALiquidityHookV5` (`0x07d8F2Dfd121B10dE3176DeAb6A8C0eaa2646aCC`) swap enforcement.
11
+ - **`V-03` Per-Slip Mutex & `$0.10` Remainder Guard:** Serializes concurrent tool calls via `SlipMutex` and prevents sub-minimum change reverts (`$0.10 USDC`, `100 sats` cbBTC, `0.000001` ETH/NARA).
12
+ - **`V-04` Circle `TokenPaymasterV08` Default:** Headless agent operations default to self-funded `USDC` network fees via Circle `TokenPaymasterV08` (`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`) + `Simple7702Account` (`0xe6Cae83BdE06E4c305530e199D7217f42808555B`).
13
+
14
+ ## Quick Start
15
+
16
+ ```bash
17
+ CRYPTOSLIP_URL="<YOUR_SLIP_URL>" npx @cryptoslip/mcp
18
+ ```
19
+
20
+ ### Claude Desktop / Claude Code / Cursor Configuration
21
+
22
+ ```json
23
+ {
24
+ "mcpServers": {
25
+ "cryptoslip": {
26
+ "command": "npx",
27
+ "args": ["-y", "@cryptoslip/mcp"],
28
+ "env": {
29
+ "CRYPTOSLIP_URL": "<YOUR_SLIP_URL>",
30
+ "CRYPTOSLIP_MAX_PER_CALL_USD": "0.50",
31
+ "CRYPTOSLIP_MAX_DAILY_USD": "5.00",
32
+ "CRYPTOSLIP_MAX_SPENDS_PER_MIN": "3"
33
+ }
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ ## Tools Exposed Over Stdio
40
+
41
+ | Tool | Purpose |
42
+ | :--- | :--- |
43
+ | `cryptoslip_status` | Redacted slip & wallet balance, active vault (`v33`), rotation status, and policy caps (zero raw keys). |
44
+ | `cryptoslip_pay_human` | Splits or creates a `#startapp=slip_...` link (or 12-char `scrypt` code) for X/Telegram/SMS human bounties (`No take-back` or revocable). |
45
+ | `cryptoslip_batch_payout` | 1-tx `Multicall3` batch dispenser (`1..500` items) returning JSON or CSV `#` links with `bc_ea68lz8s` Builder Code. |
46
+ | `cryptoslip_pay_x402_or_merchant` | Pays an HTTP `402` endpoint or merchant wallet via `splitAndPay` under `BoundedAgentPolicy` + `SlipMutex`. |
47
+ | `cryptoslip_verify_or_export_receipt` | Verifies or exports a cryptographic `PaymentReceiptBundleV1` (`JSON`, `CSV`, or printable HTML). |
48
+ | `cryptoslip_reclaim_unclaimed` | `0%`-fee `refundSlipDirect` recovery for unclaimed revocable (`cancelLockedUntil == 0`) DM slips. |
49
+ | `cryptoslip_withdraw_referrals` | Claims `0.25%` (`50/50` share) lifetime `referralCredits` on Base Mainnet. |
50
+
51
+ ## Environment Variables
52
+
53
+ | Variable | Default | Description |
54
+ | :--- | :--- | :--- |
55
+ | `CRYPTOSLIP_URL` | *(required for PocketSlip)* | `#startapp=slip_...` pocket-funds URL; rotated on boot via `Keep` (`0%` fee). |
56
+ | `CRYPTOSLIP_STATE_PATH` | `~/.cryptoslip-mcp/pocket-state.json` | `0600` local file storing rotated local signer state across restarts. |
57
+ | `CRYPTOSLIP_RPC_URL` | `https://mainnet.base.org` | Base Mainnet (`8453`) JSON-RPC endpoint. |
58
+ | `CRYPTOSLIP_MAX_PER_CALL_USD` | `"0.50"` | Maximum USD-equivalent value allowed per single spend call. |
59
+ | `CRYPTOSLIP_MAX_DAILY_USD` | `"5.00"` | Maximum rolling 24-hour USD-equivalent spend limit. |
60
+ | `CRYPTOSLIP_MAX_SPENDS_PER_MIN` | `"3"` | Sliding-window per-minute spend count limit. |
61
+ | `CRYPTOSLIP_ALLOWED_RECIPIENTS` | *(unset)* | Optional comma-separated `0x...` recipient allowlist. |
62
+ | `CRYPTOSLIP_ALLOWED_DOMAINS` | *(unset)* | Optional comma-separated HTTPS hostname allowlist for HTTP `402` endpoints. |
63
+
64
+ ## OpenClaw / Skill Manifest
65
+
66
+ See [`SKILL.md`](./SKILL.md) for the ready-to-drop skill manifest.
package/SKILL.md ADDED
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: cryptoslip-pocket-slip
3
+ description: Non-custodial Base Mainnet (8453) PocketSlip wallet and settlement MCP skill for AI agents. Provision an agent with a $5 USDC, ETH, cbBTC, or NARA CryptoSLIP URL instead of a master wallet private key; auto-rotates on boot (<1s Keep at 0% fee), enforces an out-of-context BoundedAgentPolicy spend firewall, pays HTTP 402 APIs and merchants, sends 1-tap Telegram/X/SMS human bounties, executes 1-tx Multicall3 batch payouts, verifies cryptographic payment receipts, reclaims unclaimed slips, and collects 0.25% lifetime referral rewards.
4
+ license: MIT
5
+ compatibility: Node.js >= 22. Run via `npx @cryptoslip/mcp` with `CRYPTOSLIP_URL="<YOUR_SLIP_URL>"`.
6
+ metadata:
7
+ author: nara-protocol
8
+ version: "1.0.0"
9
+ chain: base-mainnet-8453
10
+ mcp-package: "@cryptoslip/mcp"
11
+ sdk-package: "@cryptoslip/sdk"
12
+ registry-targets:
13
+ - openclaw-skills
14
+ - clawhub
15
+ - rentahuman-mcp
16
+ - claude-code
17
+ allowed-tools:
18
+ - mcp__cryptoslip__cryptoslip_status
19
+ - mcp__cryptoslip__cryptoslip_pay_human
20
+ - mcp__cryptoslip__cryptoslip_batch_payout
21
+ - mcp__cryptoslip__cryptoslip_pay_x402_or_merchant
22
+ - mcp__cryptoslip__cryptoslip_verify_or_export_receipt
23
+ - mcp__cryptoslip__cryptoslip_reclaim_unclaimed
24
+ - mcp__cryptoslip__cryptoslip_withdraw_referrals
25
+ ---
26
+
27
+ # CryptoSLIP PocketSlip Skill (`@cryptoslip/mcp`)
28
+
29
+ Give any autonomous agent bounded pocket funds on **Base Mainnet (`8453`)** using a single CryptoSLIP `#` URL — **zero master wallet private key required**.
30
+
31
+ ## Why PocketSlip Exists
32
+
33
+ 1. **Zero Master Key Exposure (`V-01` Boot Auto-Keep):** Provision the MCP server with `CRYPTOSLIP_URL="<YOUR_SLIP_URL>"` (for example, a `$5.00 USDC` slip). On startup (`bootAndRotate()`), if the slip is unrotated (`nonces == 0`), `PocketSlipVault` immediately executes an on-chain `Keep` (`0%` protocol fee), rotating `claimSigner` to a fresh local key stored with `0600` file permissions. The original `.env` link becomes invalid on-chain in under a second, capping worst-case prompt-injection exposure strictly to that single slip.
34
+ 2. **Deterministic Out-of-Context Firewall (`V-02` `BoundedAgentPolicy`):** Every signature passes through `BoundedAgentPolicy` inside the Node.js signer boundary before signing:
35
+ - Per-call spend cap (`maxPerCallUsdMicro`, default `$0.50` in micro-API mode)
36
+ - Sliding-window rate limits (`maxSpendsPerMinute`, `maxDailyUsdMicro`)
37
+ - Protocol & token contract destination denylist (`assertSafeDestination` — blocks zero/burn addresses, token contracts, vaults, routers, and public test keys)
38
+ - Optional recipient & domain allowlists (`allowedRecipients`, `allowedDomains`)
39
+ - Recursive output secret scrubber (`redactSecretsFromToolOutput`) so raw claim secrets never enter LLM telemetry logs
40
+ - Canonical Uniswap V4 `NARALiquidityHookV5` (`0x07d8F2Dfd121B10dE3176DeAb6A8C0eaa2646aCC`) enforcement for all `NARA` swaps
41
+ 3. **Serialized Spend Queue & Sub-Minimum Guard (`V-03`):** Concurrent spends serialize through per-slip `SlipMutex` with pre-flight `$0.10 USDC` (`100 sats` cbBTC / `0.000001` ETH or NARA) remainder checks on `CryptoSlipVaultV32` (`v33`: `0x3f80aa68Fb4834d6E119EE1cf932C14419Cf63EB`).
42
+ 4. **Self-Funded USDC Network Fees (`V-04`):** Headless agent calls default to Circle `TokenPaymasterV08` (`0x0578cFB241215b77442a541325d6A4E6dFE700Ec`) + `Simple7702Account` (`0xe6Cae83BdE06E4c305530e199D7217f42808555B`) so bots never consume human mobile relay quotas.
43
+
44
+ ---
45
+
46
+ ## Quick Setup (Claude Code / OpenClaw / Cursor)
47
+
48
+ Create a `$5.00 USDC` slip at `https://slip.naraprotocol.io` (or `https://cryptoslip.eth.limo`) and pass it to the MCP server environment:
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "cryptoslip": {
54
+ "command": "npx",
55
+ "args": ["-y", "@cryptoslip/mcp"],
56
+ "env": {
57
+ "CRYPTOSLIP_URL": "<YOUR_SLIP_URL>",
58
+ "CRYPTOSLIP_MAX_PER_CALL_USD": "0.50",
59
+ "CRYPTOSLIP_MAX_DAILY_USD": "5.00",
60
+ "CRYPTOSLIP_MAX_SPENDS_PER_MIN": "3"
61
+ }
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
67
+ Or via Claude Code CLI:
68
+
69
+ ```bash
70
+ claude mcp add cryptoslip -e CRYPTOSLIP_URL="<YOUR_SLIP_URL>" -- npx -y @cryptoslip/mcp
71
+ ```
72
+
73
+ ---
74
+
75
+ ## Available MCP Tools (7 Tools)
76
+
77
+ ### 1. `cryptoslip_status`
78
+ Returns the active `PocketSlipVault` summary: slip ID, vault (`v33` `0x3f80aa68Fb4834d6E119EE1cf932C14419Cf63EB`), asset, available balance, boot-rotation state, and active `BoundedAgentPolicy` limits. Zero secret keys or `#k` fragments are ever returned.
79
+
80
+ ### 2. `cryptoslip_pay_human`
81
+ Creates or splits a 1-tap `#startapp=slip_...` payout link (or 12-char `XXXX-XXXX-XXXX` off-grid `scrypt` code) to pay a human contributor over Telegram (`@cryptoslip_bot/SLIP`), X DM, Discord, or SMS:
82
+ - Supports `noTakeBack: true` (`9_999_999_999` timestamp) for instant irrevocable delivery, or revocable mode (`noTakeBack: false`) so the agent can reclaim funds via `cryptoslip_reclaim_unclaimed` if the recipient never claims.
83
+ - Only emits an outbound `#` link when `allowOutboundSlipLink` policy permits human payouts, and instructs the agent to deliver it strictly via private DM.
84
+
85
+ ### 3. `cryptoslip_batch_payout`
86
+ Packs `1..500` partner or bounty payouts (`USDC` / `cbBTC` via offline EIP-3009 `ReceiveWithAuthorization` + `MintPermit`) into **1 `Multicall3` transaction** on Base (`8453`) with Base Builder Code `bc_ea68lz8s`, returning structured JSON or CSV `#` links while preserving `creator = partnerWallet` for `0.25%` lifetime referral attribution.
87
+
88
+ ### 4. `cryptoslip_pay_x402_or_merchant`
89
+ Pays an HTTP `402` API endpoint, `withCryptoSlip()` tollbooth, or merchant wallet (`0x...` or `#startapp=pos_<address>`) from the active PocketSlip via `splitAndPay`:
90
+ - Enforces `BoundedAgentPolicy` spend cap, sliding-window rate limit, and `assertSafeDestination`.
91
+ - Retains remaining change inside a rotated `1:1` shielded child slip so the agent's balance stays private.
92
+
93
+ ### 5. `cryptoslip_verify_or_export_receipt`
94
+ Verifies an inbound `PaymentReceiptBundleV1` on Base Mainnet in a single RPC check (`verifyPaymentReceiptOnChain`), or exports a signed receipt bundle (`JSON`, `CSV`, or self-contained printable HTML) proving exact settlement.
95
+
96
+ ### 6. `cryptoslip_reclaim_unclaimed`
97
+ Executes a `0%`-fee `refundSlipDirect` on Base to recover funds from an unclaimed revocable DM slip (`cancelLockedUntil == 0` and `nonces == 0`).
98
+
99
+ ### 7. `cryptoslip_withdraw_referrals`
100
+ Reads and withdraws accumulated `0.25%` (`50/50` protocol fee share) lifetime `referralCredits` earned in `USDC`, `cbBTC`, `ETH`, or `NARA` on `CryptoSlipVaultV32`.
101
+
102
+ ---
103
+
104
+ ## Agent Operating Rules
105
+
106
+ 1. **Never paste raw `#k` URLs into public timelines.** When `cryptoslip_pay_human` generates an open `#` link, send it only inside a direct message to the intended recipient, or use `mode: "code"` (`12-char scrypt` code) for two-step verification.
107
+ 2. **Respect `BoundedAgentPolicy` refusals.** If a tool call throws a policy cap, rate-limit, or blocked-destination error, halt and ask the human operator rather than retrying in a loop.
108
+ 3. **Verify inbound payments on-chain.** Before fulfilling a paid request for another agent or user, call `cryptoslip_verify_or_export_receipt` to confirm Base Mainnet settlement finality.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
package/dist/cli.js ADDED
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ import { redactSecretsFromToolOutput } from '@cryptoslip/sdk';
3
+ import { startCryptoSlipStdioServer } from './server.js';
4
+ startCryptoSlipStdioServer().catch((err) => {
5
+ const msg = err instanceof Error ? err.message : String(err);
6
+ process.stderr.write(`[@cryptoslip/mcp] Fatal startup error: ${redactSecretsFromToolOutput(msg)}\n`);
7
+ process.exitCode = 1;
8
+ });
9
+ //# sourceMappingURL=cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,0BAA0B,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAClD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0CAA0C,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAC/E,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,3 @@
1
+ export * from './pocketSlip.js';
2
+ export * from './server.js';
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export * from './pocketSlip.js';
2
+ export * from './server.js';
3
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
@@ -0,0 +1,231 @@
1
+ import { type Address, type Hex } from 'viem';
2
+ import { BoundedAgentPolicy, SlipMutex, executeBatchPayoutSlips, type AnyAssetSymbol, type BaseCompatiblePublicClient, type BaseCompatibleWalletClient, type BoundedAgentPolicyConfig, type CreateSignedPaymentReceiptInput, type MintedPayoutSlipRecord, type PaymentReceiptBundleV1, type PolicySnapshot, type SdkAssetSymbol, type SharedTransportExecutionOptions, type VaultTag, type VerifyPaymentReceiptOptions } from '@cryptoslip/sdk';
3
+ export declare class PocketSlipError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ export interface PocketSlipPersistedState {
7
+ version: 1;
8
+ originalLineageHash: Hex;
9
+ activeSlipId: string | null;
10
+ vault: VaultTag;
11
+ asset: SdkAssetSymbol;
12
+ activeClaimPrivateKey?: Hex;
13
+ activeClaimSigner?: Address;
14
+ operatorPrivateKey: Hex;
15
+ operatorAddress: Address;
16
+ bootRotated: boolean;
17
+ bootRotationTxHash?: Hex;
18
+ updatedAt: string;
19
+ createdRevocableSlipIds: string[];
20
+ }
21
+ export interface PocketSlipVaultConfig {
22
+ /** `#startapp=slip_...` pocket-money URL (defaults to `process.env.CRYPTOSLIP_URL`). */
23
+ slipUrl?: string;
24
+ /** Local `0600` JSON file persisting the rotated key across restarts (`null` disables disk I/O). */
25
+ stateFilePath?: string | null;
26
+ /** Base Mainnet JSON-RPC endpoint (defaults to `process.env.CRYPTOSLIP_RPC_URL` or `https://mainnet.base.org`). */
27
+ rpcUrl?: string;
28
+ /** Injectable `viem` PublicClient for Base Mainnet (`8453`) or fork tests. */
29
+ publicClient?: BaseCompatiblePublicClient;
30
+ /** Optional `viem` WalletClient for direct EOA submission when desired. */
31
+ walletClient?: BaseCompatibleWalletClient;
32
+ /** Optional local operator key (`0x` + 64 hex); auto-generated and persisted (`0600`) if omitted. */
33
+ operatorPrivateKey?: Hex;
34
+ /** Out-of-context policy guard or config. */
35
+ policy?: BoundedAgentPolicy | BoundedAgentPolicyConfig;
36
+ /** Shared per-slip mutex (`V-03`). */
37
+ mutex?: SlipMutex;
38
+ /** Optional transport overrides (`bundlerFetch`, `relayClient`, `directBroadcast`, etc.). */
39
+ transportOverrides?: Partial<SharedTransportExecutionOptions>;
40
+ /** Optional injectable mint executor for tests or custom relayer pipelines. */
41
+ customBatchExecutor?: typeof executeBatchPayoutSlips;
42
+ }
43
+ export interface BootRotateResult {
44
+ bootRotated: boolean;
45
+ resumedFromLocalState: boolean;
46
+ slipId: string;
47
+ vault: VaultTag;
48
+ asset: SdkAssetSymbol;
49
+ balanceUnits: string;
50
+ humanBalance: string;
51
+ activeClaimSigner: Address;
52
+ operatorAddress: Address;
53
+ bootRotationTxHash?: Hex;
54
+ }
55
+ export interface PocketSlipStatusSummary {
56
+ initialized: boolean;
57
+ hasActivePocketSlip: boolean;
58
+ chainId: 8453;
59
+ vault: VaultTag;
60
+ vaultAddress: Address;
61
+ paymasterDefault: Address;
62
+ naraHookEnforced: Address;
63
+ slipId: string | null;
64
+ asset: SdkAssetSymbol | null;
65
+ balanceUnits: string;
66
+ humanBalance: string;
67
+ bootRotated: boolean;
68
+ bootRotationTxHash?: Hex;
69
+ activeClaimSigner: Address | null;
70
+ operatorAddress: Address;
71
+ trackedRevocableSlipIds: string[];
72
+ policy: PolicySnapshot;
73
+ }
74
+ export interface PayHumanInput {
75
+ /** Human decimal string (e.g. `"1.50"`) or atomic integer string/bigint when `amountIsAtomic` is true. */
76
+ amount: string | number | bigint;
77
+ amountIsAtomic?: boolean;
78
+ asset?: AnyAssetSymbol;
79
+ /** `true` sets `cancelLockedUntil = 9_999_999_999` (irrevocable); `false` allows `0%`-fee creator reclaim if unclaimed. */
80
+ noTakeBack?: boolean;
81
+ mode?: 'open' | 'code';
82
+ grossUpForExitFee?: boolean;
83
+ note?: string;
84
+ recipientLabel?: string;
85
+ }
86
+ export interface PayHumanResult {
87
+ slipId: string;
88
+ vault: VaultTag;
89
+ asset: SdkAssetSymbol;
90
+ humanAmount: number;
91
+ grossAmountUnits: string;
92
+ guaranteedNetClaimUnits: string;
93
+ mode: 'open' | 'code';
94
+ noTakeBack: boolean;
95
+ outboundSlipUrl: string;
96
+ claimCode?: string;
97
+ txHash: Hex;
98
+ splitTxHash?: Hex;
99
+ deliveryNotice: string;
100
+ }
101
+ export interface BatchPayoutToolInput {
102
+ items: Array<{
103
+ amount: string | number | bigint;
104
+ amountIsAtomic?: boolean;
105
+ asset?: AnyAssetSymbol;
106
+ noTakeBack?: boolean;
107
+ grossUpForExitFee?: boolean;
108
+ mode?: 'open' | 'code';
109
+ note?: string;
110
+ recipientRef?: string;
111
+ }>;
112
+ format?: 'json' | 'csv' | 'both';
113
+ }
114
+ export interface PayMerchantOrX402Input {
115
+ /** Checksummed/hex `0x...` address, `#startapp=pos_<addr>`, or `#startapp=pay_<addr>_...` link. */
116
+ recipient: string;
117
+ /** Human decimal string (e.g. `"0.25"`) or atomic units when `amountIsAtomic` is true. */
118
+ amount: string | number | bigint;
119
+ amountIsAtomic?: boolean;
120
+ /** Optional HTTPS URL of the HTTP `402` API endpoint (checked against `allowedDomains`). */
121
+ endpointUrl?: string;
122
+ /** Allows sweeping sub-minimum `< $0.10` remainder to merchant when explicitly enabled. */
123
+ allowFullCashOnDust?: boolean;
124
+ }
125
+ export declare function buildPolicyFromEnv(env?: NodeJS.ProcessEnv, overrides?: BoundedAgentPolicyConfig): BoundedAgentPolicy;
126
+ /**
127
+ * `PocketSlipVault` (`Module #1`):
128
+ * Self-rotating `$5` pocket-money vault for AI agents (`V-01` `<1s` Boot Auto-Keep,
129
+ * `V-02` `BoundedAgentPolicy` firewall, `V-03` `SlipMutex` + `$0.10` dust guard,
130
+ * and `V-04` Circle `TokenPaymasterV08` USDC gas default).
131
+ */
132
+ export declare class PocketSlipVault {
133
+ readonly publicClient: BaseCompatiblePublicClient;
134
+ readonly policy: BoundedAgentPolicy;
135
+ readonly mutex: SlipMutex;
136
+ readonly stateFilePath: string | null;
137
+ private readonly rawSlipUrl?;
138
+ private readonly walletClient?;
139
+ private readonly transportOverrides;
140
+ private readonly customBatchExecutor;
141
+ private operatorPrivateKey;
142
+ private operatorAddress;
143
+ private originalLineageHash;
144
+ private activeSlipId;
145
+ private activeVault;
146
+ private activeAsset;
147
+ private activeClaimPrivateKey?;
148
+ private activeClaimSigner?;
149
+ private bootRotated;
150
+ private bootRotationTxHash?;
151
+ private createdRevocableSlipIds;
152
+ private bootPromise;
153
+ private initialized;
154
+ constructor(config?: PocketSlipVaultConfig);
155
+ private readPersistedState;
156
+ private writePersistedState;
157
+ private syncStateToDisk;
158
+ /**
159
+ * `V-01` Boot Auto-Keep:
160
+ * Immediately checks the configured `CRYPTOSLIP_URL` on Base Mainnet. If unrotated (`nonces == 0`),
161
+ * executes `keepSlip()` (`0%` protocol fee) rotating `claimSigner` to a fresh local key persisted in
162
+ * `0600` local storage, invalidating the `.env` `#k` link on-chain in `<1s`.
163
+ */
164
+ bootAndRotate(): Promise<BootRotateResult | null>;
165
+ private performBootAndRotate;
166
+ private ensureBooted;
167
+ /**
168
+ * Tool #1: `cryptoslip_status` — Safe redacted slip/wallet balance, vault `v33`, and policy limits.
169
+ */
170
+ getStatus(): Promise<PocketSlipStatusSummary>;
171
+ /**
172
+ * Tool #2: `cryptoslip_pay_human` — Mints or splits a `No take-back` or revocable `#startapp=slip_...`
173
+ * link (or 12-char `scrypt` code) for X/Telegram/SMS human bounties.
174
+ */
175
+ payHuman(input: PayHumanInput): Promise<PayHumanResult>;
176
+ /**
177
+ * Tool #3: `cryptoslip_batch_payout` — 1-Tx `Multicall3` batch dispenser (`1..500` items) returning JSON/CSV `#` links.
178
+ */
179
+ batchPayout(input: BatchPayoutToolInput): Promise<{
180
+ count: number;
181
+ txHashes: readonly Hex[];
182
+ outboundLinks?: readonly MintedPayoutSlipRecord[];
183
+ outboundCsv?: string;
184
+ }>;
185
+ /**
186
+ * Tool #4: `cryptoslip_pay_x402_or_merchant` — `splitAndPay` with `BoundedAgentPolicy` (`V-02`),
187
+ * `SlipMutex` + `$0.10` dust guard (`V-03`), and Circle `TokenPaymasterV08` default (`V-04`).
188
+ */
189
+ payMerchantOrX402(input: PayMerchantOrX402Input): Promise<{
190
+ txHash: Hex;
191
+ parentSlipId: string;
192
+ newActiveSlipId: string | null;
193
+ merchant: Address;
194
+ asset: SdkAssetSymbol;
195
+ grossPaymentUnits: string;
196
+ feeUnits: string;
197
+ netMerchantUnits: string;
198
+ remainingChangeUnits: string;
199
+ transportTier: string;
200
+ }>;
201
+ /**
202
+ * Tool #5: `cryptoslip_verify_or_export_receipt` — Verifies or generates `PaymentReceiptBundleV1`.
203
+ */
204
+ verifyOrExportReceipt(input: {
205
+ action: 'verify';
206
+ bundle: PaymentReceiptBundleV1;
207
+ options?: VerifyPaymentReceiptOptions;
208
+ } | {
209
+ action: 'export';
210
+ receiptInput: Omit<CreateSignedPaymentReceiptInput, 'signer'>;
211
+ signWithOperatorKey?: boolean;
212
+ includeCsv?: boolean;
213
+ includeHtml?: boolean;
214
+ }): Promise<Record<string, unknown>>;
215
+ /**
216
+ * Tool #6: `cryptoslip_reclaim_unclaimed` — `0%`-fee `refundSlipDirect` for unclaimed `cancelLockedUntil == 0` DM slips.
217
+ */
218
+ reclaimUnclaimed(input: {
219
+ slipId?: string;
220
+ scanOnly?: boolean;
221
+ minAgeSeconds?: number;
222
+ }): Promise<Record<string, unknown>>;
223
+ /**
224
+ * Tool #7: `cryptoslip_withdraw_referrals` — Claims `0.25%` lifetime `referralCredits` on Base.
225
+ */
226
+ withdrawReferrals(input?: {
227
+ to?: string;
228
+ assets?: readonly AnyAssetSymbol[];
229
+ }): Promise<Record<string, unknown>>;
230
+ }
231
+ //# sourceMappingURL=pocketSlip.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pocketSlip.d.ts","sourceRoot":"","sources":["../src/pocketSlip.ts"],"names":[],"mappings":"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"}