wip: add core functions

Author: mweinschenk

.github/FUNDING.yml

@@ -1 +1 @@
-github: :vendor_name
+github: farbcode

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,11 @@
 blank_issues_enabled: false
 contact_links:
   - name: Ask a question
-    url: https://github.com/:vendor_slug/:package_name/discussions/new?category=q-a
+    url: https://github.com/farbcodegmbh/laravel-evm/discussions/new?category=q-a
     about: Ask the community for help
   - name: Request a feature
-    url: https://github.com/:vendor_slug/:package_name/discussions/new?category=ideas
+    url: https://github.com/farbcodegmbh/laravel-evm/discussions/new?category=ideas
     about: Share ideas for new features
   - name: Report a security issue
-    url: https://github.com/:vendor_slug/:package_name/security/policy
+    url: https://github.com/farbcodegmbh/laravel-evm/security/policy
     about: Learn how to notify us for sensitive bugs

.github/copilot-instructions.md

@@ -0,0 +1,110 @@
+# Laravel EVM Package - AI Coding Instructions
+
+## Architecture Overview
+
+This is a Laravel package for Ethereum Virtual Machine (EVM) blockchain interactions with server-side focus. The package provides a clean abstraction layer for:
+- **Smart contract interaction** (read/write operations)
+- **Asynchronous transaction handling** via Laravel queues
+- **EIP-1559 transaction signing** with gas fee management
+- **Multi-RPC failover** with round-robin load balancing
+- **Nonce management** to prevent transaction conflicts
+
+## Core Components
+
+### 1. Service Container Bindings (`LaravelEvmServiceProvider`)
+The package uses Laravel's service container with singleton bindings for all major components:
+- `RpcClient` → `RpcHttpClient` (handles multiple RPC URLs)
+- `ContractClient` → `ContractClientGeneric` (main API interface)  
+- `Signer` → `PrivateKeySigner` (transaction signing)
+- `NonceManager` → `LocalNonceManager` (prevents nonce conflicts)
+- `FeePolicy` → `SimpleFeePolicy` (EIP-1559 gas pricing)
+
+### 2. Contract Interaction Pattern
+```php
+// Read operations (synchronous)
+$contract = Evm::at('0xAddress', $abiJson);
+$result = $contract->call('functionName', $args);
+
+// Write operations (asynchronous via queue)
+$jobId = $contract->sendAsync('functionName', $args);
+```
+
+### 3. Transaction Lifecycle
+Write operations use `SendTransaction` job that handles:
+1. Gas estimation with configurable padding
+2. Nonce retrieval/management  
+3. EIP-1559 fee calculation
+4. Transaction signing and broadcast
+5. Receipt polling with timeout
+6. Gas price replacement attempts if stuck
+7. Event emission at each stage (`TxQueued`, `TxBroadcasted`, `TxMined`, `TxFailed`)
+
+## Key Development Patterns
+
+### Configuration-Driven Behavior
+All critical parameters are configurable via `config/evm.php`:
+- Multiple RPC endpoints (`EVM_RPC_1`, `EVM_RPC_2`, etc.)
+- Gas estimation padding (`estimate_padding: 1.2`)
+- Transaction timeouts and retry limits
+- Queue configuration for transaction jobs
+
+### Contract Interface Implementation
+Follow the `ContractClient` interface pattern when extending functionality:
+- `at()` - sets contract address/ABI
+- `call()` - synchronous reads
+- `sendAsync()` - asynchronous writes returning job ID
+- `wait()` - blocks until transaction receipt
+
+### Error Handling Strategy
+The package uses custom exceptions in `src/Exceptions/`:
+- `RpcException` for network/RPC issues
+- `GasException` for gas estimation problems  
+- `SignerException` for signing failures
+- Events for transaction state tracking rather than exceptions
+
+## Development Workflows
+
+### Testing
+```bash
+composer test          # Run Pest test suite
+composer analyse       # PHPStan static analysis  
+composer format        # Laravel Pint code formatting
+```
+
+### Adding New RPC Methods
+1. Extend `RpcClient` interface if needed
+2. Implement in `RpcHttpClient` with failover logic
+3. Add integration tests
+
+### Extending Signer Support
+1. Implement `Signer` contract
+2. Add driver configuration in `LaravelEvmServiceProvider`
+3. Ensure `privateKey()` method availability for transaction signing
+
+### Command Usage Examples
+```bash
+php artisan evm:call 0xAddress ./abi.json functionName arg1 arg2
+php artisan evm:send 0xAddress ./abi.json functionName arg1 arg2  
+php artisan evm:wait 0xTransactionHash
+php artisan evm:health
+```
+
+## Critical Dependencies
+
+- **web3p/web3.php**: ABI encoding/decoding
+- **web3p/ethereum-tx**: EIP-1559 transaction creation and signing
+- **spatie/laravel-package-tools**: Laravel package scaffolding
+
+## Environment Requirements
+
+- **Queue system required**: Redis recommended for `QUEUE_CONNECTION`
+- **Private key management**: Store `EVM_PRIVATE_KEY` securely
+- **RPC reliability**: Configure multiple `EVM_RPC_*` endpoints for redundancy
+- **Chain ID**: Must match target network (`EVM_CHAIN_ID`)
+
+## Transaction Queue Considerations
+
+- Keep queue concurrency at 1 per signing address to prevent nonce conflicts
+- Use dedicated queue (`evm-send`) to isolate blockchain operations
+- Monitor transaction events for debugging and logging
+- Failed transactions emit `TxFailed` events rather than throwing exceptions

CHANGELOG.md

@@ -1,3 +1,3 @@
 # Changelog
 
-All notable changes to `:package_name` will be documented in this file.
+All notable changes to `laravel-evm` will be documented in this file.

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) :vendor_name <author@domain.com>
+Copyright (c) farbcode GmbH <hello@farbcode.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,68 +1,47 @@
-# :package_description
+# This is my package laravel-evm
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/:vendor_slug/:package_slug/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/:vendor_slug/:package_slug/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/:vendor_slug/:package_slug/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/:vendor_slug/:package_slug/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-<!--delete-->
----
-This repo can be used to scaffold a Laravel package. Follow these steps to get started:
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/farbcodegmbh/laravel-evm.svg?style=flat-square)](https://packagist.org/packages/farbcodegmbh/laravel-evm)
+[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/farbcodegmbh/laravel-evm/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/farbcodegmbh/laravel-evm/actions?query=workflow%3Arun-tests+branch%3Amain)
+[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/farbcodegmbh/laravel-evm/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/farbcodegmbh/laravel-evm/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
+[![Total Downloads](https://img.shields.io/packagist/dt/farbcodegmbh/laravel-evm.svg?style=flat-square)](https://packagist.org/packages/farbcodegmbh/laravel-evm)
 
-1. Press the "Use this template" button at the top of this repo to create a new repo with the contents of this skeleton.
-2. Run "php ./configure.php" to run a script that will replace all placeholders throughout all the files.
-3. Have fun creating your package.
-4. If you need help creating a package, consider picking up our <a href="https://laravelpackage.training">Laravel Package Training</a> video course.
----
-<!--/delete-->
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
-
-## Support us
-
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/:package_name.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/:package_name)
-
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
-
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+A Laravel native EVM client for server side use
+RPC via Http facade  ABI encoding  EIP 1559 signing  nonces  jobs  events
 
 ## Installation
 
 You can install the package via composer:
 
 ```bash
-composer require :vendor_slug/:package_slug
+composer require farbcode/laravel-evm
 ```
 
-You can publish and run the migrations with:
+You can publish the config file with:
 
 ```bash
-php artisan vendor:publish --tag=":package_slug-migrations"
-php artisan migrate
+php artisan vendor:publish --tag="laravel-evm-config"
 ```
 
-You can publish the config file with:
 
-```bash
-php artisan vendor:publish --tag=":package_slug-config"
-```
+## env
+ EVM_CHAIN_ID=137
+ EVM_RPC_1=https://polygon-mainnet.g.alchemy.com/v2/KEY
+ EVM_PRIVATE_KEY=0xabc123...64hex
+ QUEUE_CONNECTION=redis
 
-This is the contents of the published config file:
+## Usage
 
 ```php
-return [
-];
-```
+use LaravelEvm; // Facade alias defined in composer.json
 
-Optionally, you can publish the views using
+$abi = file_get_contents(storage_path('app/abi/IntegrityAnchorSimple.abi.json'));
+$contract = LaravelEvm::at('0xYourContract', $abi);
 
-```bash
-php artisan vendor:publish --tag=":package_slug-views"
-```
+// read
+$res = $contract->call('isAnchored', [1, '0x'.$hashHex]);
 
-## Usage
-
-```php
-$variable = new VendorName\Skeleton();
-echo $variable->echoPhrase('Hello, VendorName!');
+// write non blocking
+$jobId = $contract->sendAsync('anchor', [1, '0x'.$hashHex, 'meta']);
 ```
 
 ## Testing
@@ -85,7 +64,7 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 ## Credits
 
-- [:author_name](https://github.com/:author_username)
+- [Martin Weinschenk](https://github.com/mweinschenk)
 - [All Contributors](../../contributors)
 
 ## License

composer.json

@@ -1,24 +1,28 @@
 {
-    "name": ":vendor_slug/:package_slug",
-    "description": ":package_description",
+    "name": "farbcodegmbh/laravel-evm",
+    "description": "This is my package laravel-evm",
     "keywords": [
-        ":vendor_name",
+        "farbcode",
         "laravel",
-        ":package_slug"
+        "laravel-evm"
     ],
-    "homepage": "https://github.com/:vendor_slug/:package_slug",
+    "homepage": "https://github.com/farbcodegmbh/laravel-evm",
     "license": "MIT",
     "authors": [
         {
-            "name": ":author_name",
-            "email": "author@domain.com",
+            "name": "Martin Weinschenk",
+            "email": "martin.weinschenk@farbcode.net",
             "role": "Developer"
         }
     ],
     "require": {
         "php": "^8.4",
+        "illuminate/contracts": "^11.0||^12.0",
+        "kornrunner/ethereum-address": "^0.3.0",
+        "kornrunner/keccak": "^1.1",
         "spatie/laravel-package-tools": "^1.16",
-        "illuminate/contracts": "^11.0||^12.0"
+        "web3p/ethereum-tx": "^0.4.3",
+        "web3p/web3.php": "^0.1.6"
     },
     "require-dev": {
         "laravel/pint": "^1.14",
@@ -30,18 +34,16 @@
         "pestphp/pest-plugin-laravel": "^4.0",
         "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan-deprecation-rules": "^2.0",
-        "phpstan/phpstan-phpunit": "^2.0",
-        "spatie/laravel-ray": "^1.35"
+        "phpstan/phpstan-phpunit": "^2.0"
     },
     "autoload": {
         "psr-4": {
-            "VendorName\\Skeleton\\": "src/",
-            "VendorName\\Skeleton\\Database\\Factories\\": "database/factories/"
+            "Farbcode\\LaravelEvm\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "VendorName\\Skeleton\\Tests\\": "tests/",
+            "Farbcode\\LaravelEvm\\Tests\\": "tests/",
             "Workbench\\App\\": "workbench/app/"
         }
     },
@@ -63,10 +65,10 @@
     "extra": {
         "laravel": {
             "providers": [
-                "VendorName\\Skeleton\\SkeletonServiceProvider"
+                "Farbcode\\LaravelEvm\\LaravelEvmServiceProvider"
             ],
             "aliases": {
-                "Skeleton": "VendorName\\Skeleton\\Facades\\Skeleton"
+                "LaravelEvm": "Farbcode\\LaravelEvm\\Facades\\LaravelEvm"
             }
         }
     },

config/evm.php

@@ -0,0 +1,39 @@
+<?php
+
+// config for Farbcode/LaravelEvm
+return [
+    'chain_id' => env('EVM_CHAIN_ID', 137),
+
+    // Multiple RPC urls supported. Client uses round robin with fallback.
+    'rpc_urls' => array_values(array_filter([
+        env('EVM_RPC_1'),
+        env('EVM_RPC_2'),
+        env('EVM_RPC_3'),
+    ])),
+
+    // Signer configuration.
+    'signer' => [
+        'driver' => env('EVM_SIGNER', 'private_key'),
+        'private_key' => env('EVM_PRIVATE_KEY'),
+        // 'kms_key' => env('EVM_KMS_KEY_ARN'),
+    ],
+
+    // Fee policy for EIP 1559.
+    'fees' => [
+        'min_priority_gwei' => env('EVM_MIN_PRIORITY_GWEI', 3),
+        'min_maxfee_gwei'   => env('EVM_MIN_MAXFEE_GWEI', 40),
+        'base_multiplier'   => env('EVM_BASE_MULTIPLIER', 3),
+        'replacement_factor'=> env('EVM_REPLACEMENT_FACTOR', 1.5),
+    ],
+
+    // Transaction behavior.
+    'tx' => [
+        'estimate_padding' => env('EVM_ESTIMATE_PADDING', 1.2),
+        'confirm_timeout'  => env('EVM_CONFIRM_TIMEOUT', 120), // seconds
+        'max_replacements' => env('EVM_MAX_REPLACEMENTS', 2),
+        'poll_interval_ms' => env('EVM_POLL_INTERVAL_MS', 800),
+
+        // Queue used for sending jobs. Keep concurrency at one per writer address.
+        'queue' => env('EVM_QUEUE', 'evm-send'),
+    ],
+];