Skip to content

Commit 40031d0

Browse files
committed
docs: rewrite readme
1 parent b2d91ab commit 40031d0

1 file changed

Lines changed: 126 additions & 24 deletions

File tree

README.md

Lines changed: 126 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,147 @@
11
[![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/)
22

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
54

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).
87

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
129

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.
1419

1520
## Preview
1621
![Preview](https://user-images.githubusercontent.com/4107993/38056594-b6cd6e14-3291-11e8-96e2-a771b0e9cee3.png)
1722

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+
1875
## Documentation
1976

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+
```
21107

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
28109

29-
Debian (or Ubuntu) are recommended.
30-
31-
### Getting Started
110+
```bash
111+
composer test:phpstan
112+
```
113+
114+
#### Run Unit Tests
32115

33-
1. Start the Monero daemon (`monerod`) on testnet.
34116
```bash
35-
monerod --testnet --detach
117+
composer test:unit
36118
```
37119

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+
39124
```bash
40-
monero-wallet-rpc --testnet --rpc-bind-port 28083 --disable-rpc-login --wallet-dir /path/to/wallet/directory
125+
composer test
41126
```
42127

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
44146

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

Comments
 (0)