feat: event payload support for async EVM transactions

Author: mweinschenk

src/Clients/ContractClientGeneric.php

@@ -68,7 +68,7 @@ public function estimateGas(string $data, ?string $from = null): int
         return (int) max(150000, ceil($n * $pad));
     }
 
-    public function sendAsync(string $function, array $args = [], array $opts = []): string
+    public function sendAsync(string $function, array $args = [], array $opts = [], mixed $payload = null): string
     {
         $data = $this->abi->encodeFunction($this->abiJson, $function, $args);
         $queue = (string) ($this->txCfg['queue'] ?? 'evm-send');
@@ -80,7 +80,8 @@ public function sendAsync(string $function, array $args = [], array $opts = []):
             data: $data,
             opts: array_merge($opts, ['request_id' => $requestId]),
             chainId: $this->chainId,
-            txCfg: $this->txCfg
+            txCfg: $this->txCfg,
+            payload: $payload
         ))->onQueue($queue);
 
         return $requestId;

src/Contracts/ContractClient.php

@@ -9,8 +9,12 @@ public function at(string $address, array|string $abi = []): self;
     /** Synchronous read only call returning raw hex or decoded value depending on ABI usage. */
     public function call(string $function, array $args = []): mixed;
 
-    /** Enqueue a non blocking write job. Returns job id string. */
-    public function sendAsync(string $function, array $args = [], array $opts = []): string;
+    /**
+     * Enqueue a non blocking write job. Returns job id string.
+     * Optional $payload allows attaching any serializable context (e.g. an Eloquent model) that will
+     * be forwarded to all transaction lifecycle events (TxQueued, TxBroadcasted, TxReplaced, TxMined, TxFailed).
+     */
+    public function sendAsync(string $function, array $args = [], array $opts = [], mixed $payload = null): string;
 
     /** Wait for a receipt with timeout returns receipt array or null. */
     public function wait(string $txHash, int $timeoutSec = 120, int $pollMs = 800): ?array;

src/Events/TxBroadcasted.php

@@ -6,5 +6,5 @@
 
 class TxBroadcasted
 {
-    public function __construct(public string $txHash, public array $fields) {}
+    public function __construct(public string $txHash, public array $fields, public mixed $payload = null) {}
 }

src/Events/TxFailed.php

@@ -6,5 +6,5 @@
 
 class TxFailed
 {
-    public function __construct(public string $to, public string $data, public string $reason) {}
+    public function __construct(public string $to, public string $data, public string $reason, public mixed $payload = null) {}
 }

src/Events/TxMined.php

@@ -6,5 +6,5 @@
 
 class TxMined
 {
-    public function __construct(public string $txHash, public array $receipt) {}
+    public function __construct(public string $txHash, public array $receipt, public mixed $payload = null) {}
 }

src/Events/TxQueued.php

@@ -6,5 +6,5 @@
 
 class TxQueued
 {
-    public function __construct(public string $to, public string $data) {}
+    public function __construct(public string $to, public string $data, public mixed $payload = null) {}
 }

src/Events/TxReplaced.php

@@ -11,5 +11,5 @@ class TxReplaced
      * @param  array  $newFields  Neue Felder inklusive angehobener Fees
      * @param  int  $attempt  Laufende Ersatz-Versuchsnummer (1-basiert)
      */
-    public function __construct(public string $oldTxHash, public array $newFields, public int $attempt) {}
+    public function __construct(public string $oldTxHash, public array $newFields, public int $attempt, public mixed $payload = null) {}
 }

src/Jobs/SendTransaction.php

@@ -27,11 +27,11 @@ class SendTransaction implements ShouldQueue
 {
     use InteractsWithQueue, Queueable, SerializesModels;
 
-    public function __construct(public string $address, public string $data, public array $opts, public int $chainId, public array $txCfg) {}
+    public function __construct(public string $address, public string $data, public array $opts, public int $chainId, public array $txCfg, public mixed $payload = null) {}
 
     public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, FeePolicy $fees): void
     {
-        event(new TxQueued($this->address, $this->data));
+        event(new TxQueued($this->address, $this->data, $this->payload));
 
         $from = $signer->getAddress();
 
@@ -67,7 +67,7 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
 
         $pk = method_exists($signer, 'privateKey') ? $signer->privateKey() : null;
         if (! $pk) {
-            event(new TxFailed($this->address, $this->data, 'Signer has no privateKey method'));
+            event(new TxFailed($this->address, $this->data, 'Signer has no privateKey method', $this->payload));
 
             return;
         }
@@ -78,10 +78,10 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
             $rawHex = str_starts_with($raw, '0x') ? $raw : '0x'.$raw; // ensure 0x prefix
             $txHash = $rpc->call('eth_sendRawTransaction', [$rawHex]);
             $nonces->markUsed($from, $nonce);
-            event(new TxBroadcasted($txHash, $fields));
+            event(new TxBroadcasted($txHash, $fields, $this->payload));
 
         } catch (\Throwable $e) {
-            event(new TxFailed($this->address, $this->data, 'rpc_send_error: '.$e->getMessage()));
+            event(new TxFailed($this->address, $this->data, 'rpc_send_error: '.$e->getMessage(), $this->payload));
 
             return;
         }
@@ -94,7 +94,7 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
         while (time() < $deadline) {
             $rec = $rpc->call('eth_getTransactionReceipt', [$txHash]);
             if (! empty($rec)) {
-                event(new TxMined($txHash, $rec));
+                event(new TxMined($txHash, $rec, $this->payload));
 
                 return;
             }
@@ -109,15 +109,15 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
             $fields['maxFeePerGas'] = $max;
 
             // Emit replacement attempt (before rebroadcast)
-            event(new TxReplaced($oldTxHash, $fields, $i + 1));
+            event(new TxReplaced($oldTxHash, $fields, $i + 1, $this->payload));
 
             try {
                 $raw = new EIP1559Transaction($fields)->sign($pk);
                 $rawHex = str_starts_with($raw, '0x') ? $raw : '0x'.$raw; // ensure 0x prefix
                 $txHash = $rpc->call('eth_sendRawTransaction', [$rawHex]);
-                event(new TxBroadcasted($txHash, $fields));
+                event(new TxBroadcasted($txHash, $fields, $this->payload));
             } catch (\Throwable $e) {
-                event(new TxFailed($this->address, $this->data, 'rpc_send_error_replacement_'.$i.': '.$e->getMessage()));
+                event(new TxFailed($this->address, $this->data, 'rpc_send_error_replacement_'.$i.': '.$e->getMessage(), $this->payload));
 
                 return;
             }
@@ -126,7 +126,7 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
             while (time() < $deadline) {
                 $rec = $rpc->call('eth_getTransactionReceipt', [$txHash]);
                 if (! empty($rec)) {
-                    event(new TxMined($txHash, $rec));
+                    event(new TxMined($txHash, $rec, $this->payload));
 
                     return;
                 }
@@ -137,7 +137,8 @@ public function handle(RpcClient $rpc, Signer $signer, NonceManager $nonces, Fee
         event(new TxFailed(
             $this->address,
             $this->data,
-            sprintf('no_receipt_after_%d_replacements (last maxFee=%d priority=%d)', $maxRep, $fields['maxFeePerGas'], $fields['maxPriorityFeePerGas'])
+            sprintf('no_receipt_after_%d_replacements (last maxFee=%d priority=%d)', $maxRep, $fields['maxFeePerGas'], $fields['maxPriorityFeePerGas']),
+            $this->payload
         ));
     }
 }