gun-eth 1.2.7 → 1.2.8

package/README.md

@@ -1,93 +1,147 @@
-# gun-eth
+# GUN-ETH
 
-## Description
+<img src="https://imgs.search.brave.com/RM76D4wyToxCzGffJLw33O_L3glhpIVS3KLvXehpMt8/rs:fit:500:0:0:0/g:ce/aHR0cHM6Ly93d3cu/dXNlcmxvZ29zLm9y/Zy9maWxlcy9sb2dv/cy9mZXJuYW5kb3Nh/bnR1Y2NpLzI5NDY5/X2d1bmRiLWxvZ28u/cG5n" alt="gun" width="200"/>
+<img src="https://imgs.search.brave.com/kQyriTMPqw42DEhIQj3eEKIcLZu_C4nNIVR8KtAn3lo/rs:fit:500:0:0:0/g:ce/aHR0cHM6Ly93d3cu/bG9nby53aW5lL2Ev/bG9nby9FdGhlcmV1/bS9FdGhlcmV1bS1E/aWFtb25kLUxvZ28u/d2luZS5zdmc" alt="eth" width="200"/>
 
-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.
+## 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. [Core Functions](#core-functions)
+7. [SHINE](#shine)
+8. [Standalone Mode](#standalone-mode)
+9. [Security Considerations](#security-considerations)
+10. [Contributing](#contributing)
+11. [License](#license)
+12. [Contact](#contact)
+
+## 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.
+
+## SMART CONTRACT
 
 SHINE Smart Contract deployed on Optimism Sepolia: [0x43D838b683F772F08f321E5FA265ad3e333BE9C2](https://sepolia-optimism.etherscan.io/address/0x43D838b683F772F08f321E5FA265ad3e333BE9C2)
 
 Currently, the contract is deployed only on Optimism Sepolia. In the future, it will be deployed on multiple chains.
 
-### Key Features
+## No time? Check the [TUTORIAL](./TUTORIAL.md)
+
+## KEY FEATURES
 
 - **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
+## HOW TO INSTALL
 
 ```bash
 npm install gun-eth
 ```
 
-```bash
+```javascript
 import gun from "gun";
 import "gun-eth";
 
-const gun = gun();
+const gun = Gun();
 
 await gun.generatePassword("YOUR_SIGNATURE");
 ```
 
-### How to use
+## HOW TO USE
 
 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).
 
-### Core Functions
+## CORE FUNCTIONS
 
 - `verifySignature(message, signature)`: Verifies an Ethereum signature for a given message.
 
-  ```js
+  ```javascript
   const recoveredAddress = await gun.verifySignature(message, signature);
   ```
 
 - `generatePassword(signature)`: Generates a password from an Ethereum signature.
 
-  ```js
+  ```javascript
   const password = gun.generatePassword(signature);
   ```
 
 - `createSignature(message)`: Creates an Ethereum signature for a message.
 
-  ```js
+  ```javascript
   const signature = await gun.createSignature(message);
   ```
 
 - `createAndStoreEncryptedPair(address, signature)`: Creates and stores an encrypted key pair.
 
-  ```js
+  ```javascript
   await gun.createAndStoreEncryptedPair(address, signature);
   ```
 
 - `getAndDecryptPair(address, signature)`: Retrieves and decrypts a stored key pair.
 
-  ```js
+  ```javascript
   const decryptedPair = await gun.getAndDecryptPair(address, signature);
   ```
 
 - `shine(chain, nodeId, data, callback)`: Implements SHINE for data verification and storage on the blockchain.
-  ```js
+
+  ```javascript
   gun.shine("optimismSepolia", nodeId, data, callback);
   ```
 
-### SHINE
+- `setToken(token)`: Sets a custom token for Gun operations.
+
+  ```javascript
+  gun.setToken("yourCustomToken");
+  ```
+
+- `getToken()`: Retrieves the current custom token.
+
+  ```javascript
+  const currentToken = gun.getToken();
+  ```
+
+## SHINE
 
 SHINE (Secure Hash Integrity Network Ethereum) provides a mechanism for verifying data integrity using Ethereum and Gun.js.
 
-1. **Data Storage**: When saving data, a content hash is generated and stored in both Gun.js and on the Ethereum blockchain.
-2. **Data Verification**: To verify data, the stored hash is compared with a hash generated from the data retrieved from Gun.js.
-3. **Blockchain Interaction**: The plugin interacts with an Ethereum smart contract to store and verify data hashes.
+#### SHINE Contract Configuration
+
+Currently, SHINE supports only the Optimism Sepolia network. The contract address is managed internally:
+
+```javascript
+const SHINE_OPTIMISM_SEPOLIA = "0x43D838b683F772F08f321E5FA265ad3e333BE9C2";
+```
+
+To support other chains in the future, the plugin will select the appropriate address based on the `chain` parameter provided to the `shine` function.
+
+#### SHINE Helper Functions
+
+SHINE uses several internal helper functions to interact with the blockchain:
+
+- `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.
+
+These functions are used internally by the `shine` method and are not directly exposed to the user.
 
 ### Usage Examples
 
 #### Verifying Data by NodeId
 
-```js
+```javascript
 const nodeId = "your-node-id-here";
+
 gun.shine("optimismSepolia", nodeId, null, (ack) => {
   if (ack.ok) {
     console.log("Data verified on blockchain", ack);
@@ -102,8 +156,9 @@ gun.shine("optimismSepolia", nodeId, null, (ack) => {
 
 #### Storing New Data
 
-```js
+```javascript
 const data = { message: "Hello, blockchain!" };
+
 gun.shine("optimismSepolia", null, data, (ack) => {
   if (ack.ok) {
     console.log("Data stored on Gun.js and blockchain", ack);
@@ -115,6 +170,16 @@ gun.shine("optimismSepolia", null, data, (ack) => {
 });
 ```
 
+## STANDALONE MODE
+
+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:
+
+```javascript
+gun.setStandaloneConfig("https://your-rpc-url", "your-private-key");
+```
+
+Make sure to keep your private key secure and never expose it in client-side code.
+
 ### Security Considerations
 
 - Use a secure Ethereum provider (e.g., MetaMask) when interacting with functions that require signatures.

package/TUTORIAL.md

@@ -0,0 +1,103 @@
+# Tutorial: Illuminating Your Data with SHINE in GunDB 🌟
+
+Hey there, GunDB aficionado! Ready to take your decentralized data game to the next level? Enter SHINE: your ticket to blockchain-verified data integrity. It's not just about storing data anymore; it's about making it cryptographically awesome!
+
+## Step 0: Wallet Integration - Your Blockchain Passport
+
+Before we dive into the SHINE pool, remember: this plugin requires a browser-based wallet provider. Think of it as your blockchain passport. Here's how to check if you're ready to roll:
+
+```javascript
+async function connectWallet() {
+  if (typeof window.ethereum !== "undefined") {
+    console.log("Ethereum object detected");
+    try {
+      await window.ethereum.request({ method: "eth_requestAccounts" });
+      console.log("Wallet connected successfully");
+      return true;
+    } catch (error) {
+      console.error("Wallet connection denied:", error);
+      return false;
+    }
+  } else {
+    console.log(
+      "Please install MetaMask or another Ethereum-compatible wallet"
+    );
+    return false;
+  }
+}
+
+// Make sure to call this before using SHINE
+await connectWallet();
+```
+
+Pro tip: Always ensure your wallet is connected before invoking SHINE functions. No wallet, no blockchain magic!
+
+## Step 1: Installation - Equipping Your Toolbelt
+
+Let's add SHINE to your development arsenal:
+
+```bash
+npm install gun-eth
+```
+
+If your terminal responds without errors, you're locked and loaded!
+
+## Step 2: Import - Assembling the Pieces
+
+Time to bring Gun and SHINE into your JavaScript playground:
+
+```javascript
+import Gun from "gun";
+import "gun-eth";
+const gun = Gun();
+```
+
+## Step 3: SHINE in Action - Blockchain Meets Database
+
+Let's say you've got some mission-critical data to store. Here's how you'd use SHINE to give it that blockchain-grade integrity:
+
+```javascript
+const criticalData = {
+  key1: "Encrypted message",
+  key2: "Top secret algorithm",
+  key3: "42",
+};
+
+gun.shine("optimismSepolia", null, criticalData, (ack) => {
+  if (ack.ok) {
+    console.log("Data successfully anchored to the blockchain");
+    console.log("Node ID for future reference:", ack.nodeId);
+  } else {
+    console.error("Blockchain anchoring failed:", ack.err);
+  }
+});
+```
+
+Remember, your wallet needs to be ready to sign this transaction. It's like pushing code without commit access - it just won't fly!
+
+## Step 4: Verification - Trust the Crypto, Not the Hearsay
+
+When it's time to verify your data's integrity:
+
+```javascript
+const nodeId = "your-data-node-id";
+gun.shine("optimismSepolia", nodeId, null, (ack) => {
+  if (ack.ok) {
+    console.log("Data integrity verified on the blockchain");
+    console.log("Timestamp:", ack.timestamp);
+    console.log("Last updater:", ack.updater);
+  } else {
+    console.error("Integrity check failed:", ack.err);
+  }
+});
+```
+
+Again, wallet connection is crucial. No blockchain access, no verification!
+
+## Step 5: Reap the Benefits
+
+Congratulations! You've just leveled up your data management game. Your data is now cryptographically verifiable, tamper-evident, and blockchain-secured.
+
+Remember: With SHINE, you're not just storing data; you're creating a cryptographic proof of its existence and integrity. Use this power wisely!
+
+P.S. SHINE responsibly. With great cryptographic power comes great responsibility. Happy coding, and may your data always maintain its integrity! 🚀🔐

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "gun-eth",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "A GunDB plugin for Ethereum, and Web3",
-  "main": "index.js",
+  "main": "./src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/{index.js → src/index.js}

@@ -1,98 +1,136 @@
 const Gun = require("gun/gun");
 const SEA = require("gun/sea");
 const ethers = require("ethers");
-const SHINE = require("./SHINE.json");
+const SHINE = require("../abis/SHINE.json");
 
 const SHINE_ABI = SHINE.abi;
 const SHINE_OPTIMISM_SEPOLIA = SHINE.address;
 
 let SHINE_CONTRACT_ADDRESS;
-
 let customToken = "";
 
+let rpcUrl = "";
+let privateKey = "";
+
+/**
+ * Sets standalone configuration for Gun.
+ * @param {string} newRpcUrl - The new RPC URL.
+ * @param {string} newPrivateKey - The new private key.
+ * @returns {Gun} The Gun instance for chaining.
+ */
+Gun.chain.setStandaloneConfig = function (newRpcUrl, newPrivateKey) {
+  rpcUrl = newRpcUrl;
+  privateKey = newPrivateKey;
+  console.log("Standalone configuration set");
+  return this;
+};
+
+/**
+ * Sets a custom token for Gun operations.
+ * @param {string} token - The token to be set.
+ * @returns {Gun} The Gun instance for chaining.
+ */
 Gun.chain.setToken = function (token) {
   if (typeof token === "string" && token.length > 0) {
     customToken = token;
-    console.log("Token impostato con successo:", token);
+    console.log("Token set successfully:", token);
   } else {
-    console.error("Token non valido. Deve essere una stringa non vuota.");
+    console.error("Invalid token. Must be a non-empty string.");
   }
   return this;
 };
 
+/**
+ * Retrieves the current custom token.
+ * @returns {string} The current custom token.
+ */
 Gun.chain.getToken = function () {
   return customToken;
 };
 
+// Add custom token to all 'put' operations
 Gun.on("put", function (msg) {
   const to = this.to;
-  // Usa il token personalizzato
   msg.headers = {
     token: customToken,
   };
-  to.next(msg); // passa al prossimo middleware
+  to.next(msg);
 });
 
-// Aggiungi il metodo alla catena di Gun
+/**
+ * Verifies an Ethereum signature.
+ * @param {string} message - The original message that was signed.
+ * @param {string} signature - The signature to verify.
+ * @returns {Promise<string|null>} The recovered address or null if verification fails.
+ */
 Gun.chain.verifySignature = async function (message, signature) {
   try {
     const recoveredAddress = ethers.verifyMessage(message, signature);
     return recoveredAddress;
   } catch (error) {
-    console.error("Errore durante la verifica della firma:", error);
+    console.error("Error verifying signature:", error);
     return null;
   }
 };
 
+/**
+ * Generates a password from a signature.
+ * @param {string} signature - The signature to derive the password from.
+ * @returns {string|null} The generated password or null if generation fails.
+ */
 Gun.chain.generatePassword = function (signature) {
   try {
-    // Usa SHA-256 per derivare una password dalla firma
     const hexSignature = ethers.hexlify(signature);
     const hash = ethers.keccak256(hexSignature);
-
-    console.log("Password generata:", hash);
+    console.log("Generated password:", hash);
     return hash;
   } catch (error) {
-    console.error("Errore nella generazione della password:", error);
+    console.error("Error generating password:", error);
     return null;
   }
 };
 
+/**
+ * Creates an Ethereum signature for a given message.
+ * @param {string} message - The message to sign.
+ * @returns {Promise<string|null>} The signature or null if signing fails.
+ */
 Gun.chain.createSignature = async function (message) {
   try {
-    // Controlla se window.ethereum è disponibile (metamask o altro provider)
-    if (typeof window.ethereum !== "undefined") {
-      await window.ethereum.request({ method: "eth_requestAccounts" });
-      const provider = new ethers.BrowserProvider(window.ethereum);
-      const signer = await provider.getSigner();
-      const signature = await signer.signMessage(message);
-      console.log("Firma creata:", signature);
-      return signature;
-    } else {
-      throw new Error("Provider Ethereum non trovato");
-    }
+    const signer = await getSigner();
+    const signature = await signer.signMessage(message);
+    console.log("Signature created:", signature);
+    return signature;
   } catch (error) {
-    console.error("Errore durante la creazione della firma:", error);
+    console.error("Error creating signature:", error);
     return null;
   }
 };
 
+/**
+ * Creates and stores an encrypted key pair for a given address.
+ * @param {string} address - The Ethereum address to associate with the key pair.
+ * @param {string} signature - The signature to use for encryption.
+ * @returns {Promise<void>}
+ */
 Gun.chain.createAndStoreEncryptedPair = async function (address, signature) {
   try {
     const gun = this;
     const pair = await SEA.pair();
     const encryptedPair = await SEA.encrypt(JSON.stringify(pair), signature);
-
     await gun.get("users").get(address).put({ encryptedPair });
-    console.log("Pair crittografato e archiviato per:", address);
+    console.log("Encrypted pair stored for:", address);
   } catch (error) {
-    console.error(
-      "Errore durante la creazione e l'archiviazione del pair crittografato:",
-      error
-    );
+    console.error("Error creating and storing encrypted pair:", error);
   }
 };
 
+/**
+ * Retrieves and decrypts a stored key pair for a given address.
+ * @param {string} address - The Ethereum address associated with the key pair.
+ * @param {string} signature - The signature to use for decryption.
+ * @returns {Promise<Object|null>} The decrypted key pair or null if retrieval fails.
+ */
 Gun.chain.getAndDecryptPair = async function (address, signature) {
   try {
     const gun = this;
@@ -102,22 +140,25 @@ Gun.chain.getAndDecryptPair = async function (address, signature) {
       .get("encryptedPair")
       .then();
     if (!encryptedData) {
-      throw new Error("Nessun dato crittografato trovato per questo indirizzo");
+      throw new Error("No encrypted data found for this address");
     }
-
     const decryptedPair = await SEA.decrypt(encryptedData, signature);
-
     console.log(decryptedPair);
     return decryptedPair;
   } catch (error) {
-    console.error(
-      "Errore durante il recupero e la decrittazione del pair:",
-      error
-    );
+    console.error("Error retrieving and decrypting pair:", error);
     return null;
   }
 };
 
+/**
+ * SHINE (Secure Hybrid Information and Network Environment) functionality.
+ * @param {string} chain - The blockchain to use (e.g., "optimismSepolia").
+ * @param {string} nodeId - The ID of the node to verify or write.
+ * @param {Object} data - The data to write (if writing).
+ * @param {Function} callback - Callback function to handle the result.
+ * @returns {Gun} The Gun instance for chaining.
+ */
 Gun.chain.shine = function (chain, nodeId, data, callback) {
   console.log("SHINE plugin called with:", { chain, nodeId, data });
 
@@ -137,12 +178,20 @@ Gun.chain.shine = function (chain, nodeId, data, callback) {
 
   // Funzione per ottenere il signer
   const getSigner = async () => {
-    if (typeof window.ethereum !== "undefined") {
+    if (rpcUrl && privateKey) {
+      // Modalità standalone
+      const provider = new ethers.JsonRpcProvider(rpcUrl);
+      return new ethers.Wallet(privateKey, provider);
+    } else if (
+      typeof window !== "undefined" &&
+      typeof window.ethereum !== "undefined"
+    ) {
+      // Modalità browser
       await window.ethereum.request({ method: "eth_requestAccounts" });
       const provider = new ethers.BrowserProvider(window.ethereum);
       return provider.getSigner();
     } else {
-      throw new Error("Ethereum provider not found");
+      throw new Error("No valid Ethereum provider found");
     }
   };
 
@@ -287,3 +336,5 @@ Gun.chain.shine = function (chain, nodeId, data, callback) {
 
   return gun;
 };
+
+module.exports = Gun;