# PHP Contractless RPC

`php-contractless-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/php-contractless-rpc
```

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

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

Then install it:

```bash
composer update contractless/php-contractless-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
`php-contractless-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.