gun-eth 1.3.5 → 1.4.0

package/README.md

@@ -5,42 +5,41 @@
 
 ## Table of Contents
 
-1. [DESCRIPTION](#description)
-2. [SMART CONTRACT](#smart-contract)
-3. [KEY FEATURES](#key-features)
-4. [HOW TO INSTALL](#how-to-install)
-5. [HOW TO USE](#how-to-use)
-6. [HOW IT WORKS](#how-it-works)  
-7. [CORE FUNCTIONS](#core-functions)
-8. [SHINE](#shine)
-9. [STANDALONE MODE](#standalone-mode)
-10. [SECURITY CONSIDERATIONS](#security-considerations)
-11. [CONTRIBUTING](#contributing)
-12. [LICENSE](#license)
-13. [CONTACT](#contact)
+1. [Description](#description)
+2. [Smart Contracts](#smart-contracts)
+3. [Key Features](#key-features)
+4. [Installation](#installation)
+5. [Usage](#usage)
+6. [How It Works](#how-it-works)
+7. [Core Functions](#core-functions)
+8. [Proof of Integrity](#proof-of-integrity)
+9. [Stealth Addresses](#stealth-addresses)
+10. [Local Development](#local-development)
+11. [Security Considerations](#security-considerations)
+12. [Contributing](#contributing)
+13. [License](#license)
 
-## DESCRIPTION
+## Description
 
-Gun-eth is a plugin for GunDB that integrates Ethereum and Web3 functionality. This plugin extends GunDB's capabilities by allowing interaction with the Ethereum blockchain and providing cryptographic and signature management features.
+Gun-eth is a plugin for GunDB that integrates Ethereum and Web3 functionality. This plugin extends GunDB's capabilities by enabling interaction with the Ethereum blockchain, providing cryptographic signature management, proof of integrity, and stealth address features.
 
-## SMART CONTRACT
+## Smart Contracts
 
-SHINE Smart Contract deployed on Optimism Sepolia: [0x43D838b683F772F08f321E5FA265ad3e333BE9C2](https://sepolia-optimism.etherscan.io/address/0x43D838b683F772F08f321E5FA265ad3e333BE9C2)
+- **ProofOfIntegrity Contract** (Optimism Sepolia): [address]
+- **StealthAnnouncer Contract** (Optimism Sepolia): [address]
 
-Currently, the contract is deployed only on Optimism Sepolia. In the future, it will be deployed on multiple chains.
+Currently deployed on Optimism Sepolia testnet.
 
-## No time? Check the [TUTORIAL](./TUTORIAL.md)
+## Key Features
 
-## KEY FEATURES
+- **Ethereum Signature Verification**: Verify Ethereum signatures for messages
+- **Password Generation**: Generate secure passwords from Ethereum signatures
+- **Encrypted Key Pair Management**: Create, store, and retrieve encrypted key pairs
+- **Proof of Integrity**: Verify data integrity on-chain
+- **Stealth Addresses**: Private transaction capabilities
+- **Hybrid Storage**: Support for both on-chain and off-chain data storage
 
-- **Ethereum Signature Verification**: Verify Ethereum signatures for messages.
-- **Password Generation**: Generate secure passwords from Ethereum signatures.
-- **Signature Creation**: Create Ethereum signatures for messages.
-- **Encrypted Key Pair Management**: Create, store, and retrieve encrypted key pairs.
-- **SHINE Implementation**: Implement the SHINE for data verification on the blockchain.
-- **Custom Token Management**: Set and retrieve custom tokens for Gun operations.
-
-## HOW TO INSTALL
+## Installation
 
 ```bash
 npm install gun-eth
@@ -55,14 +54,14 @@ const gun = Gun();
 await gun.generatePassword("YOUR_SIGNATURE");
 ```
 
-## HOW TO USE
+## Usage
 
 Learn more about Gun.js [here](https://gun.eco/docs/Getting-Started).
 
 Learn more about plugin implementation [here](https://github.com/amark/gun/wiki/Adding-Methods-to-the-Gun-Chain#abstraction-layers).
 
 
-## HOW IT WORKS
+## How It Works
 
 ### Create KeyPair
 
@@ -74,7 +73,7 @@ Learn more about plugin implementation [here](https://github.com/amark/gun/wiki/
 
 [![](https://mermaid.ink/img/pako:eNplUsluwjAQ_ZWRz_ADObQCEiggOLAc2iQHN56ABbGjsU2FAv_erBBBLs7Yb5lnT8ESLZB5LD3rv-TIycLOjxSU3yjc7kabnQcbtCTxgrDEa84lxTAcfsC42BskyElfpEADXAhCU65KgJEHxa0j_Lw3WuOKcvtGc4NJ-NBDldA1tyjg1ChDSjqDmVP-OG6Ik9rLL4J3qHZKdPr-Uz8IfayxD6QzUh26RnvNtRZBbTEtWprUCoxLkjJL6s6dwfRpMKsCOFIg8KWnuI9d6xt8dVAk0uTBXvHfM4LVHTfut18x5i-M9spBadskjvsXWjEWL4yVNHXe7j00vSWe1YmXYbD2nw7Uvkrn8NWAmmLeLxZNwQYsQ8q4FOX4FNVRxOwRM4yYV_4KTqeI1dvqXmK5s3p7VQnzLDkcMNLucGReys-mrFwuuEVf8gPx7LGLQlpNq2ZC60EdsJyrH607zP0f6c7pXw?type=png)](https://mermaid.live/edit#pako:eNplUsluwjAQ_ZWRz_ADObQCEiggOLAc2iQHN56ABbGjsU2FAv_erBBBLs7Yb5lnT8ESLZB5LD3rv-TIycLOjxSU3yjc7kabnQcbtCTxgrDEa84lxTAcfsC42BskyElfpEADXAhCU65KgJEHxa0j_Lw3WuOKcvtGc4NJ-NBDldA1tyjg1ChDSjqDmVP-OG6Ik9rLL4J3qHZKdPr-Uz8IfayxD6QzUh26RnvNtRZBbTEtWprUCoxLkjJL6s6dwfRpMKsCOFIg8KWnuI9d6xt8dVAk0uTBXvHfM4LVHTfut18x5i-M9spBadskjvsXWjEWL4yVNHXe7j00vSWe1YmXYbD2nw7Uvkrn8NWAmmLeLxZNwQYsQ8q4FOX4FNVRxOwRM4yYV_4KTqeI1dvqXmK5s3p7VQnzLDkcMNLucGReys-mrFwuuEVf8gPx7LGLQlpNq2ZC60EdsJyrH607zP0f6c7pXw)
 
-## CORE FUNCTIONS
+## Core Functions
 
 - `verifySignature(message, signature)`: Verifies an Ethereum signature for a given message.
 
@@ -112,91 +111,301 @@ Learn more about plugin implementation [here](https://github.com/amark/gun/wiki/
   gun.shine("optimismSepolia", nodeId, data, callback);
   ```
   
-## SHINE
+## Security Considerations
+
+- Use a secure Ethereum provider (e.g., MetaMask) when interacting with functions that require signatures.
+- Generated passwords and key pairs are sensitive. Handle them carefully and avoid exposing them.
+- Keep Gun.js and Ethereum dependencies up to date for security.
+- Be aware of gas costs associated with blockchain interactions when using SHINE.
+
+## Contributing
+
+We welcome contributions! Please open an issue or submit a pull request on GitHub.
 
-SHINE (Secure Hash Integrity Network Ethereum) provides a mechanism for verifying data integrity using Ethereum and Gun.js.
 
 
-[![](https://mermaid.ink/img/pako:eNplk1GTmjAQx79KJs_oICAiD9epQoX25Dq1006LPqRkPTMHiRODdx763S8Ez7N3PCXZ__73txvS4EJQwCFel-Kx2BCp0M9oyZH-PucL1e4XSZrF6BdItmYFUUzwFer1btCkSfm2ViHi2iGln05d2qQNHv_A7oim-Q9QksEeECWKoLUUFZrVPJqsOu3UGEVNZKKi5heX6M0lzuMnJUmhUCG4Aq4SstusrmWZOKIvecxpiIwTF6pzO6tiU2aWmx4OHYvgPd0u42fJzEiSjmRPSkYvilek5A0pzWegUEkU7BSSUAhJu-b-laJ4uPZNLoBf3wHuzUDhlTE1AN-uRO8E19Nt_W41AwepGRCHx_MlnLW3xmyeTyW08Y9zmxtBpm9YSECM_3crmQne5b8l08mCf-zqzii-d7CZrm5GumvN6ApbuAJZEUb1b9W0CUusNlDBEod6SYl8WGJzzE9aS2olFgde4FDJGiwsRX2_weGalDu9q7faGiJG7iWpLqdbwnHY4Ccc9pxxf-wEA9exPc92A384tPABh8NB33WDwdCxfcfxAy84WfhZCG0x6HuuZ49HI98PRjpojywMlGn2efcSzIMwNf6ahBbr9AJRuPoz?type=png)](https://mermaid.live/edit#pako:eNplk1GTmjAQx79KJs_oICAiD9epQoX25Dq1006LPqRkPTMHiRODdx763S8Ez7N3PCXZ__73txvS4EJQwCFel-Kx2BCp0M9oyZH-PucL1e4XSZrF6BdItmYFUUzwFer1btCkSfm2ViHi2iGln05d2qQNHv_A7oim-Q9QksEeECWKoLUUFZrVPJqsOu3UGEVNZKKi5heX6M0lzuMnJUmhUCG4Aq4SstusrmWZOKIvecxpiIwTF6pzO6tiU2aWmx4OHYvgPd0u42fJzEiSjmRPSkYvilek5A0pzWegUEkU7BSSUAhJu-b-laJ4uPZNLoBf3wHuzUDhlTE1AN-uRO8E19Nt_W41AwepGRCHx_MlnLW3xmyeTyW08Y9zmxtBpm9YSECM_3crmQne5b8l08mCf-zqzii-d7CZrm5GumvN6ApbuAJZEUb1b9W0CUusNlDBEod6SYl8WGJzzE9aS2olFgde4FDJGiwsRX2_weGalDu9q7faGiJG7iWpLqdbwnHY4Ccc9pxxf-wEA9exPc92A384tPABh8NB33WDwdCxfcfxAy84WfhZCG0x6HuuZ49HI98PRjpojywMlGn2efcSzIMwNf6ahBbr9AJRuPoz)
+## Stealth Addresses
 
+### Simple Explanation
+Stealth addresses allow you to receive payments without revealing your actual Ethereum address to anyone. It's like having a secret mailbox that only you can access, but anyone can send mail to. Each time someone wants to send you ETH, they generate a new, unique address that only you can unlock.
 
+### Key Benefits
+- **Privacy**: Your real address is never exposed
+- **Unlinkability**: Each payment uses a different address
+- **Security**: Only you can access the funds
+- **Decentralized**: Works without any central server
 
-#### SHINE Contract Configuration
+### Technical Details
+The stealth address system implements a protocol similar to Umbra, using:
 
-Currently, SHINE supports only the Optimism Sepolia network. The contract address is managed internally:
+1. **Key Pairs**:
+   - Viewing Key Pair: For decrypting payment notifications
+   - Spending Key Pair: For accessing received funds
+
+2. **Protocol Flow**:
+```mermaid
+sequenceDiagram
+    participant Bob as Sender (Bob)
+    participant Contract as StealthAnnouncer Contract
+    participant Alice as Recipient (Alice)
+    
+    Bob->>Bob: Generate stealth address using Alice's public keys
+    Bob->>Contract: Announce payment (stealthAddress, metadata)
+    Bob->>Blockchain: Send ETH to stealth address
+    Alice->>Contract: Scan for announcements
+    Alice->>Alice: Derive private key for stealth address
+    Alice->>Blockchain: Access funds using derived key
+```
+
+3. **Key Components**:
+   - **StealthAnnouncer Contract**: Manages payment announcements on-chain
+   - **GunDB Integration**: Stores encrypted key pairs and metadata
+   - **ECDH**: For shared secret generation
+   - **Key Derivation**: For stealth address generation
+
+### Usage Example
 
 ```javascript
-const SHINE_OPTIMISM_SEPOLIA = "0x43D838b683F772F08f321E5FA265ad3e333BE9C2";
+// Setup recipient (Alice)
+await gun.createAndStoreEncryptedPair(aliceAddress, aliceSignature);
+
+// Generate stealth address (Bob)
+const stealthInfo = await gun.generateStealthAddress(aliceAddress, bobSignature);
+
+// Announce payment (Bob)
+await gun.announceStealthPayment(
+  stealthInfo.stealthAddress,
+  stealthInfo.senderPublicKey,
+  stealthInfo.spendingPublicKey,
+  bobSignature,
+  { onChain: true }
+);
+
+// Recover funds (Alice)
+const recoveredWallet = await gun.recoverStealthFunds(
+  stealthAddress,
+  senderPublicKey,
+  aliceSignature,
+  spendingPublicKey
+);
 ```
 
-To support other chains in the future, the plugin will select the appropriate address based on the `chain` parameter provided to the `shine` function.
+### Features
+- **Hybrid Storage**: Supports both on-chain and off-chain announcements
+- **Dev Fee System**: Optional fee system for protocol sustainability
+- **Batch Processing**: Efficient scanning of multiple announcements
+- **Key Recovery**: Secure key pair backup and recovery
+- **Multi-chain Support**: Ready for deployment on any EVM chain
 
-#### SHINE Helper Functions
+### Security Considerations
+- Keep your viewing and spending keys secure
+- Never reuse stealth addresses
+- Verify contract addresses before interacting
+- Consider gas costs for on-chain announcements
+- Use appropriate entropy for key generation
 
-SHINE uses several internal helper functions to interact with the blockchain:
+For more technical details, check the [StealthAnnouncer.sol](./src/contracts/StealthAnnouncer.sol) contract and [stealth.js](./src/node/stealth.js) implementation.
 
-- `getSigner()`: Retrieves an Ethereum signer from the browser provider (e.g., MetaMask).
-- `verifyOnChain(nodeId, contentHash)`: Verifies data integrity on the blockchain.
-- `writeOnChain(nodeId, contentHash)`: Writes the content hash to the blockchain.
-- `getLatestRecord(nodeId)`: Retrieves the latest record associated with a nodeId from the blockchain.
+## Proof of Integrity
 
-These functions are used internally by the `shine` method and are not directly exposed to the user.
+The Proof of Integrity system provides on-chain verification of data integrity using smart contracts. This feature allows you to:
 
-### Usage Examples
+- Store cryptographic proofs of data on-chain
+- Verify data hasn't been tampered with
+- Track data modifications
+- Maintain an immutable audit trail
 
-#### Verifying Data by NodeId
+### How It Works
+
+1. When data is written:
+   - Data is stored in GunDB
+   - A content hash is generated
+   - The hash is stored on-chain via smart contract
+   - The original data remains in GunDB
+
+2. When data is verified:
+   - The current data is hashed
+   - The hash is compared with on-chain record
+   - Timestamp and updater info is retrieved
+   - Any modifications are detected
+
+### Example Usage
 
 ```javascript
-const nodeId = "your-node-id-here";
+// Write data with proof
+gun.proof("localhost", null, { message: "Hello, blockchain!" }, (ack) => {
+  if (ack.ok) {
+    console.log("Data written with proof:", ack.nodeId);
+  }
+});
 
-gun.shine("optimismSepolia", nodeId, null, (ack) => {
+// Verify data integrity
+gun.proof("localhost", nodeId, null, (ack) => {
   if (ack.ok) {
-    console.log("Data verified on blockchain", ack);
-    console.log("Timestamp:", ack.timestamp);
-    console.log("Updater:", ack.updater);
-    console.log("Latest Record:", ack.latestRecord);
-  } else {
-    console.log("Data not verified or not found", ack);
+    console.log("Data verified on blockchain");
+    console.log("Last update:", new Date(ack.timestamp * 1000));
+    console.log("Updated by:", ack.updater);
   }
 });
 ```
 
-#### Storing New Data
+### Batch Operations
+
+You can also verify multiple nodes at once:
 
 ```javascript
-const data = { message: "Hello, blockchain!" };
+gun.proof("localhost", null, [
+  { nodeId: "id1", data: "data1" },
+  { nodeId: "id2", data: "data2" }
+], callback);
+```
 
-gun.shine("optimismSepolia", null, data, (ack) => {
-  if (ack.ok) {
-    console.log("Data stored on Gun.js and blockchain", ack);
-    console.log("New Node ID:", ack.nodeId);
-    console.log("Transaction Hash:", ack.txHash);
-  } else {
-    console.log("Error storing data", ack);
-  }
-});
+## Local Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/scobru/gun-eth
+cd gun-eth
 ```
 
-## STANDALONE MODE
+2. Install dependencies:
+```bash
+yarn install
+```
 
-For users who want to run the plugin without a browser wallet, you can use the standalone mode. This requires setting up an RPC URL and a private key:
+3. Start local Hardhat node:
+```bash
+yarn start-node
+```
 
-```javascript
-gun.setStandaloneConfig("https://your-rpc-url", "your-private-key");
+4. Deploy contracts:
+```bash
+yarn deploy-local
 ```
 
-Make sure to keep your private key secure and never expose it in client-side code.
+5. Build the project:
+```bash
+yarn build
+```
 
-### Security Considerations
+6. Run examples:
+```bash
+# Test stealth addresses
+yarn test-stealth
 
-- Use a secure Ethereum provider (e.g., MetaMask) when interacting with functions that require signatures.
-- Generated passwords and key pairs are sensitive. Handle them carefully and avoid exposing them.
-- Keep Gun.js and Ethereum dependencies up to date for security.
-- Be aware of gas costs associated with blockchain interactions when using SHINE.
+# Test proof of integrity
+yarn test-proof
+```
+
+### Environment Setup
+
+Create a `.env` file with:
+
+```env
+PRIVATE_KEY=your_private_key
+RPC_URL=your_rpc_url
+CHAIN_ID=your_chain_id
+```
+
+### Testing
+
+The project includes several test examples:
+
+- `examples/eth2gun.html`: Browser demo for key pair management
+- `examples/proof.html`: Browser demo for proof of integrity
+- `examples/stealth-example.js`: Node.js demo for stealth addresses
+- `examples/proof-example.js`: Node.js demo for proof of integrity
+
+## Bundle Information
+
+The project is bundled using Rollup and provides three different formats:
+
+1. **UMD Bundle** (Browser)
+   - File: `dist/gun-eth.min.js`
+   - Usage: 
+   ```html
+   <script src="dist/gun-eth.min.js"></script>
+   ```
+
+2. **ES Module**
+   - File: `dist/gun-eth.esm.js`
+   - Usage:
+   ```javascript
+   import GunEth from 'gun-eth';
+   ```
+
+3. **CommonJS**
+   - File: `dist/gun-eth.cjs.js`
+   - Usage:
+   ```javascript
+   const GunEth = require('gun-eth');
+   ```
+
+## API Reference
+
+### Core Methods
+
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|---------|
+| `verifySignature` | Verifies an Ethereum signature | `message`, `signature` | `Promise<address>` |
+| `generatePassword` | Generates password from signature | `signature` | `string` |
+| `createSignature` | Creates an Ethereum signature | `message` | `Promise<string>` |
+| `createAndStoreEncryptedPair` | Creates and stores key pair | `address`, `signature` | `Promise<void>` |
+| `getAndDecryptPair` | Retrieves stored key pair | `address`, `signature` | `Promise<Object>` |
+| `proof` | Manages proof of integrity | `chain`, `nodeId`, `data`, `callback` | `Gun` |
+
+### Stealth Methods
+
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|---------|
+| `generateStealthAddress` | Generates stealth address | `recipientAddress`, `signature` | `Promise<Object>` |
+| `announceStealthPayment` | Announces payment | `stealthAddress`, `senderPublicKey`, `spendingPublicKey`, `signature` | `Promise<void>` |
+| `recoverStealthFunds` | Recovers funds from stealth address | `stealthAddress`, `senderPublicKey`, `signature` | `Promise<Object>` |
+
+## Security Considerations
+
+1. **Key Management**
+   - Store private keys securely
+   - Never expose signatures or passwords
+   - Use hardware wallets when possible
+
+2. **Network Security**
+   - Use secure RPC endpoints
+   - Implement rate limiting
+   - Validate all input data
+
+3. **Smart Contract Interaction**
+   - Verify contract addresses
+   - Check gas costs before transactions
+   - Monitor for contract upgrades
+
+4. **Data Privacy**
+   - Use stealth addresses for sensitive transactions
+   - Encrypt sensitive data before storage
+   - Regularly rotate keys
 
 ## Contributing
 
-We welcome contributions! Please open an issue or submit a pull request on GitHub.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Guidelines
+
+- Follow JavaScript Standard Style
+- Add tests for new features
+- Update documentation
+- Maintain backward compatibility
+
+## Support
+
+For support, please:
+
+1. Check the [documentation](https://github.com/scobru/gun-eth#readme)
+2. Search [existing issues](https://github.com/scobru/gun-eth/issues)
+3. Create a new issue if needed
 
 ## License
 
@@ -205,3 +414,9 @@ This project is released under the MIT license.
 ## Contact
 
 For questions or support, please open an issue on GitHub: https://github.com/scobru/gun-eth
+
+## Acknowledgments
+
+- [GunDB](https://gun.eco/) team
+- [Ethereum](https://ethereum.org/) community
+- All contributors