Eth Php Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require amashukov/eth-php
   

   Ensure your environment meets requirements (PHP 8.3+, ext-gmp, ext-bcmath).

2. First Use Case: Hashing an Address

   use Amashukov\Keccak\Keccak;
   
   $keccak = new Keccak();
   $hash = $keccak->hash('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
   echo $hash; // Outputs Keccak-256 hash of the address
   

3. First Use Case: ABI Encoding

   use Amashukov\AbiEncoder\AbiEncoder;
   
   $encoder = new AbiEncoder();
   $calldata = $encoder->encode('transfer(address,uint256)', ['0xRecipientAddress', 1000000000000000000]);
   echo $calldata; // Outputs encoded calldata
   

4. First Use Case: JSON-RPC Client

   use Amashukov\EthRpc\EthRpcClient;
   use Amashukov\EthRpc\JsonRpcProvider;
   use Amashukov\HttpClient\CurlHttpClient;
   
   $httpClient = new CurlHttpClient();
   $provider = new JsonRpcProvider($httpClient, 'https://mainnet.infura.io/v3/YOUR_API_KEY');
   $client = new EthRpcClient($provider);
   
   $balance = $client->getBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
   echo $balance->value; // Outputs balance in wei
   

Where to Look First

• Documentation: Each sub-package has its own README.md with detailed usage examples.
  • Keccak
  • ABI Encoder
  • EIP-1559 Signer
  • JSON-RPC Client
• Examples: Check the examples/ directory in each sub-package for practical use cases.

Implementation Patterns

Usage Patterns

1. Modular Composition

   • Use individual components based on your needs. For example, if you only need hashing, import Amashukov\Keccak\Keccak without pulling the entire stack.
   • Example workflow for signing a transaction:

     use Amashukov\Keccak\Keccak;
     use Amashukov\AbiEncoder\AbiEncoder;
     use Amashukov\Eip1559TxSigner\Eip1559Signer;
     use Amashukov\EthRpc\EthRpcClient;
     
     $keccak = new Keccak();
     $encoder = new AbiEncoder();
     $signer = new Eip1559Signer($keccak);
     $client = new EthRpcClient($provider);
     
     // Encode calldata
     $calldata = $encoder->encode('transfer(address,uint256)', ['0xRecipient', 1000000000000000000]);
     
     // Sign transaction
     $tx = $signer->sign(
         chainId: 1,
         nonce: 5,
         maxFeePerGas: 20000000000,
         maxPriorityFeePerGas: 1000000000,
         gasLimit: 21000,
         to: '0xRecipient',
         value: 0,
         data: $calldata,
         privateKey: '0xYOUR_PRIVATE_KEY'
     );
     
     // Broadcast transaction
     $txHash = $client->sendRawTransaction($tx->raw());
     

2. JSON-RPC Client Integration

   • Use the EthRpcClient for interacting with Ethereum nodes. The client supports typed value objects (VOs) for responses like Balance, Transaction, etc.
   • Example for fetching block details:

     $block = $client->getBlockByNumber(1234567);
     echo $block->hash; // Block hash
     echo $block->transactions[0]->hash; // First transaction hash
     

3. Offline Transaction Signing

   • Assemble and sign EIP-1559 transactions offline using Eip1559Signer. This is useful for security-sensitive applications where private keys should never touch an online environment.
   • Example:

     $tx = $signer->sign(
         chainId: 1,
         nonce: 5,
         maxFeePerGas: 20000000000,
         maxPriorityFeePerGas: 1000000000,
         gasLimit: 21000,
         to: '0xRecipient',
         value: 0,
         data: $calldata,
         privateKey: '0xYOUR_PRIVATE_KEY'
     );
     

Workflows

1. Smart Contract Interaction

   • Encode function calls using AbiEncoder, then send them via EthRpcClient.
   • Example for calling a function:

     $calldata = $encoder->encode('setValue(uint256)', [42]);
     $txHash = $client->call([
         'to' => '0xContractAddress',
         'data' => $calldata,
     ]);
     

2. Transaction Lifecycle

   • Prepare: Use Eip1559Signer to sign transactions offline.
   • Broadcast: Send the raw transaction via EthRpcClient.
   • Monitor: Use EthRpcClient to check transaction status.

3. Batch Operations

   • Use the RPC client to batch requests for efficiency:

     $results = $client->batch([
         'eth_getBalance' => ['0xAddress1', 'latest'],
         'eth_getBalance' => ['0xAddress2', 'latest'],
     ]);
     

Integration Tips

1. PSR-18 HTTP Client

   • Use amashukov/http-client-php for HTTP requests with the RPC client. This ensures compatibility with the PSR-18 standard.
   • Example setup:

     use Amashukov\HttpClient\CurlHttpClient;
     $httpClient = new CurlHttpClient();
     $provider = new JsonRpcProvider($httpClient, 'https://rpc-url');
     

2. Error Handling

   • The RPC client throws exceptions for errors. Catch and handle them appropriately:

     try {
         $balance = $client->getBalance('0xInvalidAddress');
     } catch (\Amashukov\EthRpc\Exception\RpcException $e) {
         echo 'Error fetching balance: ' . $e->getMessage();
     }
     

3. Testing

   • Use the parity tests mentioned in the documentation to ensure your ABI encoding and transaction signing match ethers.js behavior.
   • Example test case:

     $encoder = new AbiEncoder();
     $calldata = $encoder->encode('transfer(address,uint256)', ['0xRecipient', 1000000000000000000]);
     $this->assertEquals('0xa9059cbb000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e00000000000000000000000000000000000000000000000003635c9adc5dea0000', $calldata);
     

Gotchas and Tips

Pitfalls

1. Private Key Security

   • Never hardcode private keys in your source code. Use environment variables or secure key management systems.
   • Example of secure usage:

     $privateKey = $_ENV['PRIVATE_KEY'];
     $tx = $signer->sign(/* ... */, privateKey: $privateKey);
     

2. Gas Estimation

   • Always estimate gas limits before signing transactions to avoid failures due to insufficient gas.
   • Example:

     $gasEstimate = $client->estimateGas([
         'to' => '