|
1 | 1 | [](https://www.php-fig.org/psr/psr-12/) [](https://phpstan.org/) |
2 | 2 |
|
3 | | -# Monero Library |
4 | | -A Monero library written in PHP by the [Monero Integrations](https://monerointegrations.com) [team](https://github.com/monero-integrations/monerophp/graphs/contributors). |
| 3 | +# Monero-Crypto |
5 | 4 |
|
6 | | -## How It Works |
7 | | -This library has 3 main parts: |
| 5 | +A Monero cryptography library written in modern PHP 8 by the [Monero Integrations team](https://monerointegrations.com) and [contributors]( |
| 6 | +https://github.com/monero-integrations/monerophp/graphs/contributors). |
8 | 7 |
|
9 | | -1. A Monero daemon JSON RPC API wrapper, `daemonRPC.php` |
10 | | -2. A Monero wallet (`monero-wallet-rpc`) JSON RPC API wrapper, `walletRPC.php` |
11 | | -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. |
| 8 | +## Features |
12 | 9 |
|
13 | | -In addition to these features, there are other lower-level libraries included for portability, *eg.* an ed25519 library, a SHA3 library, *etc.* |
| 10 | +This library implements/interfaces various cryptographic functions used in Monero, such as: |
| 11 | + |
| 12 | +- Monero's base58 encoding |
| 13 | +- Monero's mnemonic seeds |
| 14 | +- Keccak hash function |
| 15 | +- Cryptonote functions on the Edwards25519 curve |
| 16 | +- Variably-sized integers (Varint) |
| 17 | + |
| 18 | +Higher-level abstractions are additionally provided for things like generating Monero private/public keys, subaddresses, etc. |
14 | 19 |
|
15 | 20 | ## Preview |
16 | 21 |  |
17 | 22 |
|
| 23 | +## Getting Started |
| 24 | + |
| 25 | +The minimum PHP version required is 8.1.0. Please make sure you also have [Composer](https://getcomposer.org/) installed. |
| 26 | + |
| 27 | +You can check your PHP version by running: |
| 28 | + |
| 29 | +```bash |
| 30 | +php -v |
| 31 | +``` |
| 32 | + |
| 33 | +### Extensions |
| 34 | + |
| 35 | +The `bcmath` extension is required. |
| 36 | + |
| 37 | +It is **strongly recommended** to use the `gmp` extension for about 100x faster calculations (as opposed to BCMath). |
| 38 | + |
| 39 | +To check what extensions are installed, run: |
| 40 | + |
| 41 | +```bash |
| 42 | +php -m |
| 43 | +``` |
| 44 | + |
| 45 | +### Installation |
| 46 | + |
| 47 | +#### From Packagist |
| 48 | + |
| 49 | +```bash |
| 50 | +composer require monero-integrations/monero-crypto |
| 51 | +``` |
| 52 | + |
| 53 | +#### From Source |
| 54 | + |
| 55 | +```bash |
| 56 | +git clone https://github.com/monero-integrations/monerophp.git |
| 57 | +cd monerophp |
| 58 | +composer install |
| 59 | +``` |
| 60 | + |
| 61 | +### Usage |
| 62 | + |
| 63 | +From here, you can use the library in your PHP project. For example: |
| 64 | + |
| 65 | +```php |
| 66 | +require 'vendor/autoload.php'; |
| 67 | + |
| 68 | +// To get a list of available mnemonic wordlists |
| 69 | +use MoneroIntegrations\MoneroCrypto\Mnemonic; |
| 70 | +$wordlists = Mnemonic::getWordsetList(); |
| 71 | + |
| 72 | +echo "Available wordlists: " . implode(', ', $wordlists) . PHP_EOL; |
| 73 | +``` |
| 74 | + |
18 | 75 | ## Documentation |
19 | 76 |
|
20 | | -Documentation can be found in the [`/docs`](https://github.com/sneurlax/monerophp/tree/master/docs) folder. |
| 77 | +Documentation is still a work-in-progress, but the library is well-documented with PHPDoc comments. |
| 78 | + |
| 79 | +Current documentation can be found in the [`/docs`](./docs/) folder. |
| 80 | + |
| 81 | +## Development |
| 82 | + |
| 83 | +The project uses several development tools to ensure code quality and consistency: |
| 84 | + |
| 85 | +1. PHP CodeSniffer: Used to check the code style against the PSR-12 standard. |
| 86 | +2. PHPStan: Static analysis tool to find bugs and improve code quality. |
| 87 | +3. PHPUnit: Testing framework for running unit tests. |
| 88 | +4. Laravel Pint: Code style fixer for PSR-12 compliance. |
| 89 | + |
| 90 | +### Running Tests |
| 91 | + |
| 92 | +To ensure everything is working correctly, you can run the tests and code quality checks using Composer scripts: |
| 93 | + |
| 94 | +#### Lint Code |
| 95 | + |
| 96 | +```bash |
| 97 | +composer lint |
| 98 | +``` |
| 99 | + |
| 100 | +#### Test Lint |
| 101 | + |
| 102 | +Run linting on your code and test files: |
| 103 | + |
| 104 | +```bash |
| 105 | +composer test:lint |
| 106 | +``` |
21 | 107 |
|
22 | | -## Configuration |
23 | | -### Requirements |
24 | | - - Monero daemon (`monerod`) |
25 | | - - Webserver with PHP, for example XMPP, Apache, or NGINX |
26 | | - - cURL PHP extension for JSON RPC API(s) |
27 | | - - GMP PHP extension for about 100x faster calculations (as opposed to BCMath) |
| 108 | +#### Analyze Code with PHPStan |
28 | 109 |
|
29 | | -Debian (or Ubuntu) are recommended. |
30 | | - |
31 | | -### Getting Started |
| 110 | +```bash |
| 111 | +composer test:phpstan |
| 112 | +``` |
| 113 | + |
| 114 | +#### Run Unit Tests |
32 | 115 |
|
33 | | -1. Start the Monero daemon (`monerod`) on testnet. |
34 | 116 | ```bash |
35 | | -monerod --testnet --detach |
| 117 | +composer test:unit |
36 | 118 | ``` |
37 | 119 |
|
38 | | -2. Start the Monero wallet RPC interface (`monero-wallet-rpc`) on testnet. |
| 120 | +#### Run All Tests and Checks |
| 121 | + |
| 122 | +This will run linting, PHPStan analysis, and unit tests: |
| 123 | + |
39 | 124 | ```bash |
40 | | -monero-wallet-rpc --testnet --rpc-bind-port 28083 --disable-rpc-login --wallet-dir /path/to/wallet/directory |
| 125 | +composer test |
41 | 126 | ``` |
42 | 127 |
|
43 | | -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.) |
| 128 | +### Standards |
| 129 | + |
| 130 | +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. |
| 131 | + |
| 132 | +### Contributions |
| 133 | + |
| 134 | +We welcome contributions! If you have an idea or fix, please follow these steps: |
| 135 | + |
| 136 | +1. Fork the repository |
| 137 | +2. Create a branch with your changes |
| 138 | +3. Make your changes |
| 139 | +4. Submit a pull request (PR) with a clear description of the changes |
| 140 | + |
| 141 | +Please ensure your code passes all tests and adheres to our coding standards before submitting a pull request. |
| 142 | + |
| 143 | +For any questions or issues, feel free to reach out to the maintainers or open an issue on GitHub. |
| 144 | + |
| 145 | +## License |
44 | 146 |
|
45 | | -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. |
| 147 | +This library is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information. |
0 commit comments