Contractless-PHP-RPC/README.md

# PHP Contractless 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 PHP GD extension
- The PHP OpenSSL extension
- 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
```

Until the package is published, add it as a Composer path repository:

```json
{
  "repositories": [
    {
      "type": "path",
      "url": "../contractless-php-rpc"
    }
  ],
  "require": {
    "contractless/contractless-php-rpc": "@dev"
  }
}
```

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 can load a normal Contractless wallet file directly:

```php
use Contractless\Rpc\Wallet\Credentials;

$credentials = Credentials::fromWalletFile(
    '/private/path/contractless.wallet',
    'wallet decryption key',
);
```

The loader decodes all supported Contractless private-key image orientations,
verifies the encrypted payload HMAC, decrypts the Falcon private key, proves
that the public and private keys match, and verifies the wallet's canonical
short address.

Wallet files and decryption keys must remain outside public web directories,
logs, repositories, and client-visible configuration.

Verify a wallet file and decryption key before using them in an application:

```bash
php examples/load_wallet.php /private/path/contractless.wallet 'wallet decryption key'
```

Successful output confirms that the image was decoded, its encrypted payload
was authenticated and decrypted, the Falcon keypair matches, and the wallet
address is valid.

Raw Falcon key bytes remain supported for applications that already manage
their own protected key storage:

```php
$credentials = Credentials::fromHex($publicKeyHex, $privateKeyHex);
```

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