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:

composer require contractless/contractless-php-rpc

Then install it:

composer update contractless/contractless-php-rpc

Basic Use

<?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:

$reply = $client->submitTransaction($signedTransactionHex);

The first transaction builder covers the transfer used by faucets and ordinary currency, token, NFT, and RWA transfers:

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

composer install
composer test

Preparing The Composer Package

Validate the package before publishing:

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.