@sudobility/contracts 1.17.69 → 1.17.70

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.
Files changed (2) hide show
  1. package/README.md +61 -392
  2. package/package.json +8 -6
package/README.md CHANGED
@@ -1,432 +1,101 @@
1
- # Multi-Chain Decentralized Messaging Contracts
1
+ # @sudobility/contracts
2
2
 
3
- [![Version](https://img.shields.io/npm/v/@johnqh/mail_box_contracts)](https://www.npmjs.com/package/@johnqh/mail_box_contracts)
4
- [![Tests](https://img.shields.io/badge/tests-116%20passing-green)](#testing)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](#typescript-support)
6
- [![Multi-Chain](https://img.shields.io/badge/chains-EVM%20%7C%20Solana-purple)](#supported-chains)
3
+ Multi-chain decentralized messaging system supporting EVM chains and Solana with USDC-based fees, revenue sharing, delegation management, and a unified TypeScript client. Uses a two-tier fee model (Priority and Standard) with a 90/10 revenue split and 60-day claim periods.
7
4
 
8
- A comprehensive multi-chain decentralized messaging system supporting both **EVM chains** and **Solana** with USDC fee integration, delegation management, and revenue sharing capabilities.
9
-
10
- > **🤖 AI-Optimized**: This project includes comprehensive documentation, patterns, and tooling specifically designed for AI-assisted development. See [`AI_ASSISTANT_QUICKSTART.md`](./AI_ASSISTANT_QUICKSTART.md) and [`CLAUDE.md`](./CLAUDE.md) for AI development guides.
11
-
12
- ## 🏗️ Project Overview
13
-
14
- This messaging system enables decentralized communication with built-in economic incentives through a two-tier fee system and revenue sharing mechanism. The system automatically detects your wallet type and routes to the appropriate blockchain implementation.
15
-
16
- ### 🌟 Core Features
17
-
18
- - **🔗 Multi-Chain Support**: Works seamlessly on EVM chains (Ethereum, Polygon, etc.) and Solana
19
- - **🤖 Automatic Chain Detection**: Detects wallet type and routes to appropriate implementation
20
- - **👥 Delegation System**: Delegate message handling with rejection capability
21
- - **📧 Two-Tier Messaging**: Priority (revenue share) vs Standard (fee-only) tiers
22
- - **💰 Revenue Sharing**: 90% back to senders, 10% to platform
23
- - **⏰ Time-based Claims**: 60-day claim period for revenue shares
24
- - **🛡️ Type-Safe**: Full TypeScript support across all chains
25
- - **⬆️ Upgradeable**: UUPS proxy pattern (EVM) and native upgradeability (Solana)
26
-
27
- ## 📦 NPM Package Installation
5
+ ## Installation
28
6
 
29
7
  ```bash
30
- # Install the unified multi-chain TypeScript client library
31
- npm install @johnqh/mail_box_contracts
32
-
33
- # Or with yarn
34
- yarn add @johnqh/mail_box_contracts
8
+ bun add @sudobility/contracts
35
9
  ```
36
10
 
37
- ## 📱 Platform Support
38
-
39
- The package automatically detects your platform and loads the appropriate implementation:
11
+ Peer dependencies: `viem` (>=2.0.0), `@solana/web3.js` (>=1.95.0), `@solana/spl-token` (>=0.4.0). Optional: `react`, `@tanstack/react-query` (for React hooks).
40
12
 
41
- | Environment | Import | Resolves to |
42
- |-------------|--------|-------------|
43
- | React Native (Metro) | `@sudobility/contracts` | React Native build |
44
- | Browser (webpack/vite) | `@sudobility/contracts` | Web build |
45
- | Node.js | `@sudobility/contracts` | Web build |
46
-
47
- ### Auto-Detection (Recommended)
13
+ ## Usage
48
14
 
49
15
  ```typescript
50
- // Works everywhere - auto-detects platform
51
- import { OnchainMailerClient } from '@sudobility/contracts';
52
- ```
53
-
54
- ### Explicit Imports
55
-
56
- ```typescript
57
- // Force specific platform
58
- import { OnchainMailerClient } from '@sudobility/contracts/web';
59
- import { OnchainMailerClient } from '@sudobility/contracts/react-native';
60
-
61
- // Chain-specific imports
16
+ import { OnchainMailerClient, WalletDetector } from '@sudobility/contracts';
62
17
  import { EVMMailerClient } from '@sudobility/contracts/evm';
63
18
  import { SolanaMailerClient } from '@sudobility/contracts/solana';
64
- ```
65
-
66
- ### React Native Setup
19
+ import { MailerProvider, useFees, useMessaging } from '@sudobility/contracts/react';
67
20
 
68
- React Native requires polyfills to be imported first in your app entry point:
21
+ // Unified client -- stateless, auto-detects chain type
22
+ const client = new OnchainMailerClient();
69
23
 
70
- ```typescript
71
- // index.js (MUST be the first import)
72
- import '@sudobility/contracts/react-native/polyfills';
24
+ // Send a message (works on any chain)
25
+ await client.sendMessage(wallet, chainInfo, 'Subject', 'Body', { revenueShare: true });
73
26
 
74
- import { AppRegistry } from 'react-native';
75
- import App from './App';
76
- AppRegistry.registerComponent('YourApp', () => App);
27
+ // Delegate, claim revenue, manage fees
28
+ await client.delegateTo(wallet, chainInfo, delegateAddress);
29
+ await client.claimRevenue(wallet, chainInfo);
30
+ const fee = await client.getSendFee(chainInfo);
77
31
  ```
78
32
 
79
- Then use the client normally in your app:
80
-
81
- ```typescript
82
- // App.tsx - auto-detected as React Native
83
- import { OnchainMailerClient, verifyPolyfills } from '@sudobility/contracts';
84
-
85
- // Optional: verify polyfills loaded correctly
86
- const { success, missing } = verifyPolyfills();
87
- if (!success) console.error('Missing polyfills:', missing);
88
- ```
33
+ ### React Integration
89
34
 
90
- **Required React Native dependencies:**
35
+ ```tsx
36
+ import { MailerProvider, useMessaging, useFees } from '@sudobility/contracts/react';
91
37
 
92
- ```bash
93
- npm install react-native-get-random-values buffer react-native-url-polyfill text-encoding
38
+ function App() {
39
+ return (
40
+ <MailerProvider>
41
+ <MessagingUI />
42
+ </MailerProvider>
43
+ );
44
+ }
94
45
  ```
95
46
 
96
- See [`docs/REACT_NATIVE.md`](./docs/REACT_NATIVE.md) for complete React Native setup guide.
97
-
98
- ## 🚀 Quick Start - Unified Multi-Chain Client
99
-
100
- ### Option 1: Using ChainConfig with RpcHelpers (Recommended)
101
-
102
- The simplest way to initialize clients using API keys - all chain information is automatically derived:
47
+ ### React Native
103
48
 
104
49
  ```typescript
105
- import { Chain, ChainConfig } from '@sudobility/types';
106
- import { RpcHelpers } from '@sudobility/configs';
107
- import { buildChainConfig } from '@johnqh/mail_box_contracts';
108
- import { MailerClient } from '@johnqh/mail_box_contracts';
109
-
110
- // Step 1: Create config with just chain enum and API keys
111
- const chainConfig: ChainConfig = {
112
- chain: Chain.ETH_MAINNET,
113
- alchemyApiKey: process.env.ALCHEMY_API_KEY,
114
- etherscanApiKey: process.env.ETHERSCAN_MULTICHAIN_API_KEY
115
- };
116
-
117
- // Step 2: All chain info is automatically derived!
118
- const chainInfo = RpcHelpers.deriveChainInfo(chainConfig);
119
- console.log('Using:', chainInfo.name, 'at', chainInfo.rpcUrl);
120
- console.log('USDC:', chainInfo.usdcAddress);
121
-
122
- // Step 3: Build unified config and initialize client
123
- const config = buildChainConfig(chainConfig, '0x...'); // Your mailer contract
124
- const client = new MailerClient(config.evm.contracts.mailer, publicClient);
125
-
126
- // Works with any chain - just change the Chain enum!
127
- // Chain.BASE_MAINNET, Chain.POLYGON_MAINNET, Chain.SOLANA_MAINNET, etc.
128
- ```
129
-
130
- **Benefits:**
131
-
132
- - ✅ Single source of truth (Chain enum + API keys)
133
- - ✅ No hardcoded RPC URLs or addresses
134
- - ✅ Easy to switch between networks
135
- - ✅ Type-safe with full IDE autocomplete
136
- - ✅ Consistent across EVM and Solana
137
-
138
- See [`examples/config-usage.ts`](./examples/config-usage.ts) for complete examples.
139
-
140
- ### Option 2: Using Pre-configured Configs
141
-
142
- ```typescript
143
- import { OnchainMailerClient, TESTNET_CHAIN_CONFIG } from '@johnqh/mail_box_contracts';
144
-
145
- // Works with ANY wallet - automatically detects chain!
146
- const client = new OnchainMailerClient(wallet, TESTNET_CHAIN_CONFIG);
147
-
148
- // Same API works for both EVM and Solana
149
- await client.sendMessage("Hello Multi-Chain!", "This works on any blockchain!", true);
150
- await client.delegateTo("delegate-address"); // Format automatically validated
151
- await client.claimRevenue(); // Chain-agnostic revenue claiming
152
-
153
- console.log('Running on:', client.getChainType()); // 'evm' or 'solana'
154
- ```
155
-
156
- ## 🔧 Chain-Specific Usage
157
-
158
- ### EVM Chains (Ethereum, Polygon, Arbitrum, etc.)
159
-
160
- ```typescript
161
- import { OnchainMailerClient } from '@johnqh/mail_box_contracts';
162
- import { ethers } from 'ethers';
163
-
164
- // The unified client automatically detects EVM wallets
165
- const wallet = {
166
- address: "0x...",
167
- request: async () => {},
168
- signTransaction: async (tx: any) => tx
169
- };
170
-
171
- const client = new OnchainMailerClient(wallet, EVM_CHAIN_CONFIG);
172
-
173
- // Send priority message with revenue sharing
174
- await client.sendMessage("Hello EVM!", "Decentralized message", true);
175
-
176
- // Delegate to another address
177
- await client.delegateTo("0x...");
178
-
179
- // Claim revenue share
180
- await client.claimRevenue();
181
- ```
182
-
183
- ### Solana
184
-
185
- ```typescript
186
- import { OnchainMailerClient, Wallet } from '@johnqh/mail_box_contracts';
187
- import { Keypair, Transaction } from '@solana/web3.js';
188
-
189
- // Create a wallet from keypair
190
- const keypair = Keypair.generate();
191
- const wallet: Wallet = {
192
- publicKey: keypair.publicKey,
193
- signTransaction: async (tx) => { tx.partialSign(keypair); return tx; },
194
- signAllTransactions: async (txs) => { txs.forEach(tx => tx.partialSign(keypair)); return txs; },
195
- };
196
-
197
- const client = new OnchainMailerClient(wallet, SOLANA_CHAIN_CONFIG);
198
-
199
- // Send priority message with revenue sharing
200
- await client.sendMessage("Hello Solana!", "Decentralized message", true);
201
-
202
- // Delegate to another address
203
- await client.delegateTo("...");
204
-
205
- // Claim revenue share
206
- await client.claimRevenue();
207
- ```
208
-
209
- ### TypeScript Support
210
-
211
- Full TypeScript support with auto-generated contract types:
212
-
213
- ```typescript
214
- import type {
215
- Mailer,
216
- MockUSDC
217
- } from 'mail_box_contracts/typechain-types';
218
-
219
- // Fully typed contract interactions
220
- const tx: ContractTransaction = await mailer.sendPriority(to, subject, body);
221
- const receipt: ContractReceipt = await tx.wait();
222
- ```
223
-
224
- ## 📁 Project Structure
225
-
226
- ```
227
- mail_box_contracts/
228
- ├── contracts/ # EVM smart contracts (Solidity)
229
- │ ├── MailService.sol # EVM delegation management
230
- │ ├── Mailer.sol # EVM messaging with revenue sharing
231
- │ └── MockUSDC.sol # Test USDC token
232
- ├── programs/ # Solana programs (Rust)
233
- │ └── mailer/ # Solana messaging and delegation program
234
- ├── src/ # Multi-chain TypeScript clients
235
- │ ├── evm/ # EVM-specific clients
236
- │ ├── solana/ # Solana-specific clients
237
- │ ├── unified/ # Cross-chain unified client
238
- │ ├── react-native/ # React Native entry point & polyfills
239
- │ └── utils/ # Shared utilities & validation
240
- ├── test/ # Comprehensive test suites (116 tests)
241
- │ ├── evm/ # EVM contract tests (75 tests)
242
- │ ├── solana/ # Solana program tests
243
- │ └── unified/ # Cross-chain client tests (41 tests)
244
- ├── typechain-types/ # Auto-generated TypeScript types
245
- ├── examples/ # Complete usage examples
246
- └── CLAUDE.md # AI assistant documentation
247
- ```
248
-
249
- ## 🚀 Quick Start
250
-
251
- ### Prerequisites
252
-
253
- - Node.js 16+
254
- - npm or yarn
255
-
256
- ### Installation
257
-
258
- ```bash
259
- # Clone and install dependencies
260
- npm install
261
-
262
- # Compile contracts and generate types
263
- npm run compile
264
-
265
- # Run comprehensive test suite (116 tests)
266
- npm test
267
-
268
- # Deploy to local network
269
- npm run deploy:local
50
+ import '@sudobility/contracts/react-native/polyfills'; // Must be first import
51
+ import { OnchainMailerClient } from '@sudobility/contracts/react-native';
270
52
  ```
271
53
 
272
- ## 📋 Smart Contracts
273
-
274
- ### MailService Contract
275
-
276
- **Purpose**: Domain registration and delegation management
277
-
278
- **Key Functions**:
279
-
280
- - `delegateTo(address)` - Delegate email handling (10 USDC fee)
281
- - `rejectDelegation(address)` - Reject unwanted delegations
282
- - `registerDomain(string, bool)` - Register domains (100 USDC fee)
283
- - `setRegistrationFee(uint256)` - Owner fee management
284
-
285
- **Fees**:
286
-
287
- - Domain Registration: 100 USDC
288
- - Delegation: 10 USDC
289
-
290
- ### Mailer Contract
291
-
292
- **Purpose**: Message sending with revenue sharing
54
+ ## API
293
55
 
294
- **Message Types**:
56
+ ### Entry Points
295
57
 
296
- - **Priority Messages**: Full fee (0.1 USDC) + 90% revenue share
297
- - `sendPriority(subject, body)`
298
- - `sendPriorityPrepared(mailId)`
299
- - **Standard Messages**: 10% fee only (0.01 USDC)
300
- - `send(subject, body)`
301
- - `sendPrepared(mailId)`
58
+ | Import Path | Contents |
59
+ |-------------|----------|
60
+ | `@sudobility/contracts` | `OnchainMailerClient`, `WalletDetector`, unified types |
61
+ | `@sudobility/contracts/evm` | `EVMMailerClient`, `Mailer__factory`, ABI |
62
+ | `@sudobility/contracts/solana` | `SolanaMailerClient`, Solana types |
63
+ | `@sudobility/contracts/react` | `MailerProvider`, query hooks, mutation hooks |
64
+ | `@sudobility/contracts/react-native` | Unified client + polyfills |
302
65
 
303
- **Revenue Model**:
66
+ ### Smart Contracts
304
67
 
305
- - Senders pay fees to send messages to themselves
306
- - Priority senders get 90% back as claimable revenue
307
- - 60-day claim period for revenue shares
308
- - Expired shares go to contract owner
68
+ - **EVM (Solidity 0.8.24)**: UUPS upgradeable proxy, soft-fail fee pattern, permission system for contract-to-wallet authorization
69
+ - **Solana (Rust, native)**: No Anchor, Borsh serialization, PDA-based state accounts
309
70
 
310
- ## 🧪 Testing
311
-
312
- Comprehensive test coverage with 116 passing tests:
71
+ ## Development
313
72
 
314
73
  ```bash
315
- # Run all tests
316
- npm test
317
-
318
- # Test categories:
319
- # ✅ EVM Tests (75 tests) - Contract functionality, fees, revenue sharing
320
- # ✅ Unified Tests (41 tests) - Cross-chain client, validation, wallet detection
74
+ bun install
75
+ bun run compile # Compile EVM contracts (generates typechain-types/)
76
+ bun run build # Build all targets (EVM + Solana + unified + react-native)
77
+ bun test # Run all tests (EVM + Solana + unified)
78
+ bun run typecheck # TypeScript checking
79
+ bun run lint # ESLint
80
+ bun run format # Prettier
321
81
  ```
322
82
 
323
- ### Test Highlights
324
-
325
- - Fee calculation verification
326
- - Event emission testing
327
- - Revenue sharing mechanics
328
- - Time-based claim expiration
329
- - Error condition handling
330
- - Edge cases and security
331
-
332
- ## 🔧 Development Commands
83
+ ### Deployment
333
84
 
334
85
  ```bash
335
- # Essential commands (run these frequently!)
336
- npm run compile # Compile contracts + generate TypeScript types
337
- npm test # Run all 116 tests (75 EVM + 41 Unified)
338
- npm run build # Build TypeScript files
339
-
340
- # AI-Optimized commands
341
- npm run ai:dev # Show AI helper commands + status
342
- npm run ai:status # Quick project health check
343
- npm run ai:build # Clean build everything
344
- npm run ai:test # Run comprehensive test suite (116 tests)
345
- npm run ai:check # TypeScript + ESLint validation
346
-
347
- # Development
348
- npx hardhat node # Start local blockchain
349
- npm run deploy:local # Deploy to local network
350
- npm run clean # Clean artifacts
86
+ bun run deploy:evm:sepolia # Deploy to Sepolia
87
+ bun run deploy:evm:mainnet # Deploy to Ethereum mainnet
88
+ bun run deploy:solana:devnet # Deploy Solana program
89
+ bun run verify:evm:mainnet # Etherscan verification
351
90
  ```
352
91
 
353
- ## 📊 Architecture
354
-
355
- ### Revenue Sharing Flow
356
-
357
- 1. **Priority Message**: User pays 0.1 USDC
358
- 2. **Revenue Split**: 90% claimable by sender, 10% to owner
359
- 3. **Claim Period**: 60 days to claim revenue share
360
- 4. **Expiration**: Unclaimed shares go to contract owner
361
-
362
- ### Delegation System
363
-
364
- 1. **Delegate**: Pay 10 USDC to delegate email handling
365
- 2. **Reject**: Delegates can reject unwanted delegations
366
- 3. **Clear**: Set delegate to address(0) to clear
367
-
368
- ## 🛠️ TypeScript Integration
369
-
370
- Full TypeScript support with auto-generated types:
371
-
372
- ```typescript
373
- import { OnchainMailerClient } from "@johnqh/mail_box_contracts";
374
-
375
- // Type-safe contract interactions using unified client
376
- const client = new OnchainMailerClient(wallet, chainConfig);
377
- await client.delegateTo(delegateAddress);
378
- await client.sendMessage("Subject", "Body", true); // priority message
379
- await client.claimRevenue();
380
- ```
381
-
382
- ## 🔐 Security Features
383
-
384
- - **Owner-only functions** protected by `onlyOwner` modifier
385
- - **USDC transfer validation** - operations only proceed if payment succeeds
386
- - **Time-based expiration** for revenue claims
387
- - **Address validation** for delegation rejection
388
- - **Comprehensive error handling** with custom errors
389
-
390
- ## 🤖 AI-Assisted Development
391
-
392
- This project is optimized for AI-assisted development with comprehensive documentation, patterns, and tooling:
393
-
394
- ### Quick Start for AI Assistants
395
-
396
- 1. **Read**: [`AI_ASSISTANT_QUICKSTART.md`](./AI_ASSISTANT_QUICKSTART.md) - Essential guide for AI development
397
- 2. **Reference**: [`CLAUDE.md`](./CLAUDE.md) - Comprehensive AI assistant documentation
398
- 3. **Patterns**: [`docs/AI_DEVELOPMENT_PATTERNS.md`](./docs/AI_DEVELOPMENT_PATTERNS.md) - Development patterns and examples
399
- 4. **Config**: [`.ai-config.json`](./.ai-config.json) - AI tool configuration
400
-
401
- ### AI Development Features
402
-
403
- - **🔧 AI Commands**: `npm run ai:dev` for AI-optimized development workflows
404
- - **📊 Test Coverage**: 116 tests with detailed patterns for AI reference
405
- - **📝 Rich Documentation**: Comprehensive JSDoc comments and inline examples
406
- - **🎯 Success Metrics**: Clear validation criteria and checklists
407
- - **⚡ Quick Validation**: `npm run ai:check` for TypeScript + ESLint
408
- - **🔍 Project Status**: `npm run ai:status` for health check
409
-
410
- ### Documentation Structure
411
-
412
- - **Primary Guide**: [`CLAUDE.md`](./CLAUDE.md) - Main AI assistant documentation
413
- - **Quick Reference**: [`AI_ASSISTANT_QUICKSTART.md`](./AI_ASSISTANT_QUICKSTART.md) - Fast setup
414
- - **Development Patterns**: [`docs/AI_DEVELOPMENT_PATTERNS.md`](./docs/AI_DEVELOPMENT_PATTERNS.md) - Code examples
415
- - **Upgradeability Guide**: [`docs/UPGRADEABILITY.md`](./docs/UPGRADEABILITY.md) - Contract upgrade procedures
416
- - **Examples**: [`examples/`](./examples/) - Working code samples
417
-
418
- ## 🤝 Contributing
419
-
420
- 1. Fork the repository
421
- 2. Create feature branch: `git checkout -b feature/new-feature`
422
- 3. Add comprehensive tests for new functionality
423
- 4. Ensure all 116 tests pass: `npm test`
424
- 5. Submit pull request
425
-
426
- ## 📄 License
92
+ ## Related Packages
427
93
 
428
- MIT License - see LICENSE file for details.
94
+ - `@sudobility/configs` -- chain configuration, RPC helpers
95
+ - `@sudobility/types` -- shared types (Chain, ChainType)
96
+ - `@sudobility/mail_box_types` -- response types (MessageSendResponse, etc.)
97
+ - `@0xmail/indexer` -- blockchain indexer consuming contract events
429
98
 
430
- ---
99
+ ## License
431
100
 
432
- **Built with**: Hardhat, TypeScript, Solidity ^0.8.24, Ethers v6, React Native
101
+ BUSL-1.1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sudobility/contracts",
3
- "version": "1.17.69",
3
+ "version": "1.17.70",
4
4
  "type": "module",
5
5
  "main": "dist/unified/src/unified/index.js",
6
6
  "types": "dist/unified/src/unified/index.d.ts",
@@ -53,7 +53,9 @@
53
53
  "peerDependencies": {
54
54
  "@solana/spl-token": ">=0.4.0",
55
55
  "@solana/web3.js": ">=1.95.0",
56
- "@sudobility/mail_box_types": "^1.0.15",
56
+ "@sudobility/configs": "^0.0.68",
57
+ "@sudobility/mail_box_types": "^1.0.16",
58
+ "@sudobility/types": "^1.9.57",
57
59
  "@tanstack/react-query": ">=5.0.0",
58
60
  "buffer": ">=6.0.0",
59
61
  "react": "^18.0.0 || ^19.0.0",
@@ -265,7 +267,9 @@
265
267
  "@solana/spl-token": "^0.4.14",
266
268
  "@solana/wallet-adapter-base": "^0.9.27",
267
269
  "@solana/web3.js": "^1.98.4",
268
- "@sudobility/mail_box_types": "^1.0.15",
270
+ "@sudobility/configs": "^0.0.68",
271
+ "@sudobility/mail_box_types": "^1.0.16",
272
+ "@sudobility/types": "^1.9.57",
269
273
  "@tanstack/react-query": "^5.90.1",
270
274
  "@typechain/hardhat": "^9.1.0",
271
275
  "@types/chai": "^4.3.20",
@@ -293,9 +297,7 @@
293
297
  "viem": "^2.38.4"
294
298
  },
295
299
  "dependencies": {
296
- "@openzeppelin/contracts": "^5.4.0",
297
- "@sudobility/configs": "^0.0.67",
298
- "@sudobility/types": "^1.9.55"
300
+ "@openzeppelin/contracts": "^5.4.0"
299
301
  },
300
302
  "overrides": {
301
303
  "bigint-buffer": "^1.1.5"