From 2b57a73b5ceb4cb9fd4f2f23002fc712b3ac0aaf Mon Sep 17 00:00:00 2001
From: viraladmin <00purple@gmail.com>
Date: Sat, 25 Jul 2026 14:05:20 -0600
Subject: [PATCH] added example usage to README

---
 README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 86 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 3e4017f..90a8579 100644
--- a/README.md
+++ b/README.md
@@ -308,6 +308,89 @@ Direct Skein hashing:
 $digest = skein_hash($data, 256);
 ```
 
-Direct Contractless Falcon handling requires the public-key SHAKE256 prefix and
-raw-message marker. `php-contractless-rpc` applies that format automatically,
-so application developers should use its `NativeCrypto` class.
+## Direct Falcon Signing And Verification
+
+Contractless uses `Falcon-padded-512`. Do not substitute the variable-length
+`Falcon-512` algorithm.
+
+Falcon keys and signatures are binary data. Load and store them without text,
+hexadecimal, Base64, or character-encoding conversions unless the application
+explicitly performs and reverses that conversion.
+
+Contractless Falcon signatures use a SHAKE256 prefix derived from the public
+key, followed by the raw-message marker and the original message:
+
+```text
+SHAKE256(public_key, 64 bytes) || 0x00 || 0x00 || original_message
+```
+
+### Sign A Message
+
+```php
+<?php
+
+declare(strict_types=1);
+
+$message = 'Message to sign';
+$publicKey = file_get_contents('public-key.bin');
+$privateKey = file_get_contents('private-key.bin');
+
+if ($publicKey === false || $privateKey === false) {
+    throw new RuntimeException('Unable to load the Falcon keys.');
+}
+
+$falcon = new OQS_SIGNATURE('Falcon-padded-512');
+$adaptedMessage =
+    contractless_shake256($publicKey, 64)
+    . "\0\0"
+    . $message;
+
+$signature = '';
+
+if ($falcon->sign($signature, $adaptedMessage, $privateKey) !== 0) {
+    throw new RuntimeException('Falcon signing failed.');
+}
+
+if (strlen($signature) !== 666) {
+    throw new RuntimeException('Invalid Contractless signature length.');
+}
+
+file_put_contents('signature.bin', $signature);
+```
+
+### Verify A Signature
+
+```php
+<?php
+
+declare(strict_types=1);
+
+$message = 'Message to sign';
+$publicKey = file_get_contents('public-key.bin');
+$signature = file_get_contents('signature.bin');
+
+if ($publicKey === false || $signature === false) {
+    throw new RuntimeException('Unable to load the public key or signature.');
+}
+
+if (strlen($signature) !== 666) {
+    throw new RuntimeException('Invalid Contractless signature length.');
+}
+
+$falcon = new OQS_SIGNATURE('Falcon-padded-512');
+$adaptedMessage =
+    contractless_shake256($publicKey, 64)
+    . "\0\0"
+    . $message;
+
+if ($falcon->verify($adaptedMessage, $signature, $publicKey) !== 0) {
+    throw new RuntimeException('Falcon signature verification failed.');
+}
+
+echo "Signature verified.\n";
+```
+
+These examples expose the low-level module behavior for testing and debugging.
+Applications should normally use the `NativeCrypto` class provided by
+`php-contractless-rpc`, which applies the Contractless message framing
+automatically.