diff --git a/README.md b/README.md index 5762cb3..50e8cb0 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,147 @@ [![PHPCS PSR-12](https://img.shields.io/badge/PHPCS-PSR–12-226146.svg)](https://www.php-fig.org/psr/psr-12/) [![PHPStan ](.github/phpstan.svg)](https://phpstan.org/) -# Monero Library -A Monero library written in PHP by the [Monero Integrations](https://monerointegrations.com) [team](https://github.com/monero-integrations/monerophp/graphs/contributors). +# Monero-Crypto -## How It Works -This library has 3 main parts: +A Monero cryptography library written in modern PHP 8 by the [Monero Integrations team](https://monerointegrations.com) and [contributors]( +https://github.com/monero-integrations/monerophp/graphs/contributors). -1. A Monero daemon JSON RPC API wrapper, `daemonRPC.php` -2. A Monero wallet (`monero-wallet-rpc`) JSON RPC API wrapper, `walletRPC.php` -3. A Monero/Cryptonote toolbox, `cryptonote.php`, with both lower level functions used in Monero related cryptography and higher level methods for things like generating Monero private/public keys. +## Features -In addition to these features, there are other lower-level libraries included for portability, *eg.* an ed25519 library, a SHA3 library, *etc.* +This library implements/interfaces various cryptographic functions used in Monero, such as: + +- Monero's base58 encoding +- Monero's mnemonic seeds +- Keccak hash function +- Cryptonote functions on the Edwards25519 curve +- Variably-sized integers (Varint) + +Higher-level abstractions are additionally provided for things like generating Monero private/public keys, subaddresses, etc. ## Preview ![Preview](https://user-images.githubusercontent.com/4107993/38056594-b6cd6e14-3291-11e8-96e2-a771b0e9cee3.png) +## Getting Started + +The minimum PHP version required is 8.1.0. Please make sure you also have [Composer](https://getcomposer.org/) installed. + +You can check your PHP version by running: + +```bash +php -v +``` + +### Extensions + +The `bcmath` extension is required. + +It is **strongly recommended** to use the `gmp` extension for about 100x faster calculations (as opposed to BCMath). + +To check what extensions are installed, run: + +```bash +php -m +``` + +### Installation + +#### From Packagist + +```bash +composer require monero-integrations/monero-crypto +``` + +#### From Source + +```bash +git clone https://github.com/monero-integrations/monerophp.git +cd monerophp +composer install +``` + +### Usage + +From here, you can use the library in your PHP project. For example: + +```php +require 'vendor/autoload.php'; + +// To get a list of available mnemonic wordlists +use MoneroIntegrations\MoneroCrypto\Mnemonic; +$wordlists = Mnemonic::getWordsetList(); + +echo "Available wordlists: " . implode(', ', $wordlists) . PHP_EOL; +``` + ## Documentation -Documentation can be found in the [`/docs`](https://github.com/sneurlax/monerophp/tree/master/docs) folder. +Documentation is still a work-in-progress, but the library is well-documented with PHPDoc comments. + +Current documentation can be found in the [`/docs`](./docs/) folder. + +## Development + +The project uses several development tools to ensure code quality and consistency: + +1. PHP CodeSniffer: Used to check the code style against the PSR-12 standard. +2. PHPStan: Static analysis tool to find bugs and improve code quality. +3. PHPUnit: Testing framework for running unit tests. +4. Laravel Pint: Code style fixer for PSR-12 compliance. + +### Running Tests + +To ensure everything is working correctly, you can run the tests and code quality checks using Composer scripts: + +#### Lint Code + +```bash +composer lint +``` + +#### Test Lint + +Run linting on your code and test files: + +```bash +composer test:lint +``` -## Configuration -### Requirements - - Monero daemon (`monerod`) - - Webserver with PHP, for example XMPP, Apache, or NGINX - - cURL PHP extension for JSON RPC API(s) - - GMP PHP extension for about 100x faster calculations (as opposed to BCMath) +#### Analyze Code with PHPStan -Debian (or Ubuntu) are recommended. - -### Getting Started +```bash +composer test:phpstan +``` + +#### Run Unit Tests -1. Start the Monero daemon (`monerod`) on testnet. ```bash -monerod --testnet --detach +composer test:unit ``` -2. Start the Monero wallet RPC interface (`monero-wallet-rpc`) on testnet. +#### Run All Tests and Checks + +This will run linting, PHPStan analysis, and unit tests: + ```bash -monero-wallet-rpc --testnet --rpc-bind-port 28083 --disable-rpc-login --wallet-dir /path/to/wallet/directory +composer test ``` -3. Edit `example.php` with your the IP address of `monerod` and `monero-wallet-rpc` (use `127.0.0.1:28081` and `127.0.0.1:28083`, respectively, for testnet.) +### Standards + +We follow the PSR-12 coding standard. Please make sure your code adheres to these guidelines. You can use Laravel Pint to automatically fix code style issues. + +### Contributions + +We welcome contributions! If you have an idea or fix, please follow these steps: + +1. Fork the repository +2. Create a branch with your changes +3. Make your changes +4. Submit a pull request (PR) with a clear description of the changes + +Please ensure your code passes all tests and adheres to our coding standards before submitting a pull request. + +For any questions or issues, feel free to reach out to the maintainers or open an issue on GitHub. + +## License -4. Serve `example.php` with your webserver (*eg.* XMPP, Apache/Apache2, NGINX, *etc.*) and navigate to it. If everything has been set up correctly, information from your Monero daemon and wallet will be displayed. +This library is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information. \ No newline at end of file