155 lines
4.6 KiB
Markdown
155 lines
4.6 KiB
Markdown
# Contractless PHP RPC
|
|
|
|
`contractless-php-rpc` connects PHP applications directly to a Contractless
|
|
node. It implements the authenticated binary RPC protocol without invoking
|
|
Contractless CLI programs.
|
|
|
|
The package is intended for faucets, block explorers, wallets, application
|
|
backends, and other public Contractless integrations.
|
|
|
|
## Scope
|
|
|
|
The client includes public blockchain lookups, wallet and address lookups,
|
|
mempool lookups, asset lookups, loan lookups, storage lookups, governance
|
|
lookups, wallet registration, signed transaction submission, and an RPC
|
|
interface restricted to application-safe commands.
|
|
|
|
Miner relay commands, network mapping changes, monitor-state commands, node
|
|
setup synchronization, and server-owner IP controls are intentionally not
|
|
exposed.
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.1 or newer, running as a 64-bit build
|
|
- The `skein` module from `contractless-php-crypto`
|
|
- The `oqsphp` module from `contractless-php-crypto`
|
|
|
|
Contractless uses the same Falcon key and signature sizes as
|
|
`Falcon-padded-512`, but its FN-DSA signing mode requires a small message
|
|
adaptation. `NativeCrypto` performs that adaptation automatically.
|
|
|
|
## Installation
|
|
|
|
Install and enable `contractless-php-crypto` first. Its repository contains the
|
|
native module build, installation, and compatibility-test instructions.
|
|
|
|
When this package is available through Packagist:
|
|
|
|
```bash
|
|
composer require contractless/contractless-php-rpc
|
|
```
|
|
|
|
Then install it:
|
|
|
|
```bash
|
|
composer update contractless/contractless-php-rpc
|
|
```
|
|
|
|
## Basic Use
|
|
|
|
```php
|
|
<?php
|
|
|
|
require __DIR__ . '/vendor/autoload.php';
|
|
|
|
use Contractless\Rpc\Client;
|
|
use Contractless\Rpc\Crypto\NativeCrypto;
|
|
use Contractless\Rpc\Transport\StreamTransport;
|
|
use Contractless\Rpc\Wallet\Credentials;
|
|
|
|
$credentials = Credentials::fromHex(
|
|
getenv('CONTRACTLESS_PUBLIC_KEY'),
|
|
getenv('CONTRACTLESS_PRIVATE_KEY'),
|
|
);
|
|
$crypto = new NativeCrypto();
|
|
|
|
$client = new Client(
|
|
new StreamTransport('127.0.0.1', 50050),
|
|
$crypto,
|
|
$credentials,
|
|
);
|
|
|
|
echo $client->totalBalance(
|
|
'ab13318c26250b048db92920a80a86127c933b0c.cltc',
|
|
);
|
|
```
|
|
|
|
RPC replies are returned as their original bytes. Commands that return JSON can
|
|
be decoded with `json_decode($reply, true, flags: JSON_THROW_ON_ERROR)`. Binary
|
|
block, torrent, header, and transaction replies remain available without a
|
|
lossy conversion.
|
|
|
|
## Transaction Submission
|
|
|
|
`submitTransaction()` accepts the complete serialized signed transaction as a
|
|
hexadecimal string:
|
|
|
|
```php
|
|
$reply = $client->submitTransaction($signedTransactionHex);
|
|
```
|
|
|
|
The first transaction builder covers the transfer used by faucets and ordinary
|
|
currency, token, NFT, and RWA transfers:
|
|
|
|
```php
|
|
use Contractless\Rpc\Transaction\TransferBuilder;
|
|
|
|
$transfer = (new TransferBuilder($crypto, $credentials))->create(
|
|
sender: 'sender-address.cltc',
|
|
receiver: 'receiver-address.cltc',
|
|
coin: 'CLTC',
|
|
value: 2_500_000_000,
|
|
fee: 2_500,
|
|
);
|
|
|
|
$reply = $client->submitSignedTransaction($transfer);
|
|
```
|
|
|
|
Transaction builders are a separate layer over the protocol client. This keeps
|
|
transport and node access stable when new transaction types are introduced.
|
|
|
|
## Transaction Builders
|
|
|
|
- `TransferBuilder`: currency, token, NFT, and RWA transfers
|
|
- `AssetBuilder`: token creation, token issuance, NFT/RWA creation, burns, and vanity addresses
|
|
- `AgreementBuilder`: two-party swaps and loan contracts
|
|
- `MiscellaneousBuilder`: marketing records, loan payments, and collateral claims
|
|
- `StorageBuilder`: storage keys, bool, signed and unsigned integers, strings, and deletion
|
|
- `GovernanceBuilder`: proposal keys, proposal votes, and activation votes
|
|
|
|
Swaps and loans return `DualSignedTransaction`. The first signer exports it,
|
|
the second signer imports it and calls `signNext()`, and only a complete result
|
|
can be converted with `toSignedTransaction()` and broadcast.
|
|
|
|
The 128-bit storage methods accept decimal strings. This preserves the complete
|
|
Rust `u128` and `i128` ranges instead of silently losing precision through PHP
|
|
integers or floating-point numbers.
|
|
|
|
## Wallet Material
|
|
|
|
The library accepts raw Falcon public and private key bytes. It does not read or
|
|
decrypt a Contractless private-key image. A server application should load keys
|
|
from protected secrets and must never place them in a public web directory.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
composer install
|
|
composer test
|
|
```
|
|
|
|
## Preparing The Composer Package
|
|
|
|
Validate the package before publishing:
|
|
|
|
```bash
|
|
composer validate --strict
|
|
composer install
|
|
composer test
|
|
```
|
|
|
|
Commit `composer.json`, `README.md`, `src/`, and `tests/` to the
|
|
`contractless-php-rpc` repository. Create a release tag such as `v0.1.0`, then
|
|
submit the repository URL to Packagist. Future version tags become installable
|
|
Composer releases.
|