{"id":22082942,"url":"https://github.com/evelynnmimijae/web3-plugin-faucettestnet2","last_synced_at":"2026-02-18T07:31:24.882Z","repository":{"id":242448630,"uuid":"809566883","full_name":"evelynnmimijae/web3-plugin-faucettestnet2","owner":"evelynnmimijae","description":"web3.js plugin (second attempt). Original code and idea placed second in the ChainSafe Ideathon bounty category in LearnWeb3's D.I. Hackathon. ","archived":false,"fork":false,"pushed_at":"2024-11-17T22:12:27.000Z","size":722,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-14T02:15:26.531Z","etag":null,"topics":["blockchain-technology","testnet-eth","web3js"],"latest_commit_sha":null,"homepage":"https://msha.ke/faucetplugin","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evelynnmimijae.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-03T02:43:54.000Z","updated_at":"2024-11-17T22:12:31.000Z","dependencies_parsed_at":"2024-07-30T04:01:22.340Z","dependency_job_id":"b8e7c0e6-d494-4f14-90b5-c606fcffeba1","html_url":"https://github.com/evelynnmimijae/web3-plugin-faucettestnet2","commit_stats":null,"previous_names":["evelynnmimijae/web3-plugin-faucettestnet2"],"tags_count":0,"template":false,"template_full_name":"web3/web3.js-plugin-template","purl":"pkg:github/evelynnmimijae/web3-plugin-faucettestnet2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evelynnmimijae%2Fweb3-plugin-faucettestnet2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evelynnmimijae%2Fweb3-plugin-faucettestnet2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evelynnmimijae%2Fweb3-plugin-faucettestnet2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evelynnmimijae%2Fweb3-plugin-faucettestnet2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evelynnmimijae","download_url":"https://codeload.github.com/evelynnmimijae/web3-plugin-faucettestnet2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evelynnmimijae%2Fweb3-plugin-faucettestnet2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265839673,"owners_count":23836725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain-technology","testnet-eth","web3js"],"created_at":"2024-12-01T00:08:40.795Z","updated_at":"2025-10-19T01:35:10.111Z","avatar_url":"https://github.com/evelynnmimijae.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# web3.js Faucet Plugin for Testnets \n(created using the [ChainSafe/Web3.js web3-plugin-template](https://github.com/web3/web3.js-plugin-template)) \n\n## Overview\nThe Faucet Plugin is a utility designed to facilitate interactions with the Ethereum blockchain through the Web3.js library. It provides functionality for preparing and sending transactions, specifically tailored to request Ether from a faucet. This plugin is part of a larger ecosystem that aims to simplify managing and interacting with Ethereum assets.\n\nFeatures\nPreparation of Transactions: The plugin offers a method to prepare a transaction requesting Ether from a faucet. This involves creating a transaction object with the recipient's address, the amount of Ether requested, and other necessary details such as gas limit and nonce.\n\nFuture Features *(the vision)*\nUser request handling: Request validation—Validates user requests to ensure they meet the criteria for receiving Ether (e.g., valid Ethereum address format). Rate limiting—Implements rate limiting to prevent abuse of the faucet and ensure fair distribution of Ether.\n\nDatabase integration with Tableland: Address Verification—Checks the Tableland database to verify if a user’s address has already claimed Ether, preventing double-spending. Claim Record Management—Updates the Tableland database to mark an address as having claimed Ether after a successful transaction.\n\nEthereum Blockchain Interaction: Transaction Sending—Uses web3.js to send transactions from the faucet’s Ethereum address to the user’s address, transferring the requested amount of testnet Ether. Gas Management—Automatically sets appropriate gas prices and gas limits for transactions to ensure they are processed efficiently.\n\nSmart Contract Support (Optional): Contract Interaction—If the faucet uses smart contracts for more complex logic (e.g., time-locked claims), the plugin can interact with these contracts using web3.js. Event Listening—The plugin listens for specific events emitted by the smart contracts to trigger actions (e.g., updating the database when a user claims Ether).\n\nUser feedback and Error handling: Confirmation Messages provide feedback to the user upon successful Ether distribution, including the transaction hash for verification. \n\nSecurity Measures: Secure Storage of Private Keys—Ensures that the faucet’s private key is securely stored and not exposed, protecting the faucet’s funds. Encryption—Uses encryption for sensitive data, such as API keys for Tableland, to enhance security.\n\nCustomization and Extensibility: Customizable Rules allow for customization of rules, such as the amount of Ether distributed per request or the eligibility criteria. \n\n## Usage\nInstallation\nTo use the Faucet Plugin, ensure you have Node.js installed on your system. Then, create a new project directory and initialize a new Node.js project:\n\n`mkdir my-project \u0026\u0026 cd my-project\nnpm init -y`\n\nInstall the required dependencies\n`npm install web3 crypto-js`\n\nImplementation\nFirst, import the necessary modules and define the `FaucetPlugin` class:\n\n```\nimport Web3 from 'web3';\nimport crypto from 'crypto';\n\nconst generateMockPrivateKey = (): string =\u003e {\n  return '0x' + crypto.randomBytes(32).toString('hex');\n};\n\nconst mockPrivateKey = generateMockPrivateKey();\n\nexport class FaucetPlugin {\n  public pluginNamespace = \"faucet\";\n  public web3: Web3;\n\n  constructor(web3Instance: Web3) {\n    this.web3 = web3Instance;\n  }\n\n  public async requestEther(address: string, amount: number): Promise\u003cany\u003e {\n    // Implementation details...\n  }\n\n  public async signAndSendTransaction(transaction: any, privateKey: string): Promise\u003cany\u003e {\n    // Implementation details...\n  }\n}\n```\n### Example Usage\nHere's an example of how to instantiate the FaucetPlugin and use its methods:\n\n```\nconst web3 = new Web3('https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID');\n\nconst faucetPlugin = new FaucetPlugin(web3);\n\n// Prepare a transaction\nconst transaction = await faucetPlugin.requestEther('0xRecipientAddress', 10);\n\n// Sign and send the transaction\nconst signedTransaction = await faucetPlugin.signAndSendTransaction(transaction, mockPrivateKey);\n```\n### Testing\nThe Faucet Plugin supports unit testing to ensure its functionality remains intact. Jest is recommended for testing due to its simplicity and integration with JavaScript projects. Install Jest and its types:\n\n`npm install --save-dev jest @types/jest ts-jest`\n\nConfigure Jest to work with TypeScript by adding a jest.config.js file:\n\n`module.exports = {\n  preset: 'ts-jest',\n  testEnvironment: 'node',\n};\n`\nWrite tests for the `FaucetPlugin` methods to verify their correctness and edge cases.\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevelynnmimijae%2Fweb3-plugin-faucettestnet2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevelynnmimijae%2Fweb3-plugin-faucettestnet2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevelynnmimijae%2Fweb3-plugin-faucettestnet2/lists"}