remitmd 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7726bbaff2286aa99b1f12cf78138e376d620b6063dfc2c844cc3334d9d3af56
-  data.tar.gz: 438d8d1cff61e10468d5ef368bde13ffc291a977362ba6d4bde447f1bbaf8892
+  metadata.gz: 1d8076d587f455a8a8f5bd4e80dc542a14cd11226bda0784c9816b45710f526c
+  data.tar.gz: '005762609902918f053fa2ce4c6b387f6e9af441770c212c9eb913d083113bf8'
 SHA512:
-  metadata.gz: 54b55932ceeff519a091e3a745e862feae46ccf9fd9dcc53ce66a6556f11c9a641c57f96ec10b2d82d7d391deb931caff6402263edb320027d3db9ffd6dd213c
-  data.tar.gz: 0aae67743e0462a6081ad907f97203d921b456beef974a81df3825c5b324e377d0c9702b8f72a7e7fed7e213ec8a2dab0455ac2c55f4b4e6148ee46cbbe8881c
+  metadata.gz: 939eea68d169df0628da6639dccb8f3e99961c7c12790f28c26c79e95933f1a93e8543034402eef3360a0f0697fa8346ef5409ac51b50d6801a6943faed94db4
+  data.tar.gz: bb7e3e396f9db6a9d8b03ea1cd8d01af21bf21d4682072212fbd0de7ef23250beb0659b1a5d20c97416a7fe7703a03f4ac0567db4bbbbbecf2f760de64541d58

data/README.md

@@ -43,7 +43,7 @@ wallet = Remitmd::RemitWallet.from_env
 # Optional: REMITMD_CHAIN (default: "base"), REMITMD_API_URL
 ```
 
-Permits are auto-signed. Every payment method fetches the on-chain USDC nonce, signs an EIP-2612 permit, and includes it automatically.
+Permits are auto-signed. Every payment method calls the server's `/permits/prepare` endpoint, signs the hash, and includes the permit automatically.
 
 ## CLI Signer (Recommended)
 
@@ -55,7 +55,7 @@ The CLI signer delegates key management to the `remit` CLI binary, which holds y
 # Windows: winget install remit-md.remit
 # Linux:   curl -fsSL https://remit.md/install.sh | sh
 
-export REMIT_KEY_PASSWORD=your-keystore-password
+export REMIT_SIGNER_KEY=your-keystore-password
 ```
 
 ```ruby
@@ -200,8 +200,7 @@ wallet.close_tab(tab_id, final_amount: nil, provider_sig: nil)
 wallet.sign_tab_charge(tab_contract, tab_id, total_charged, call_count)  # String
 
 # EIP-2612 Permit (auto-signed when omitted from payment methods)
-wallet.sign_permit(spender, amount, deadline: nil)                       # PermitSignature
-wallet.sign_usdc_permit(spender, value, deadline, nonce, usdc_address: nil) # PermitSignature
+wallet.sign_permit(flow, amount)                                         # PermitSignature
 
 # Streams
 wallet.create_stream(payee, rate_per_second, max_total, permit: nil)  # Stream
@@ -275,24 +274,15 @@ Remitmd::RemitWallet.new(private_key: key, chain: "base_sepolia")  # Base Sepoli
 
 ### Manual Permit Signing
 
-Permits are auto-signed by default. If you need manual control (custom deadline, pre-signed permits, or offline signing), pass a `PermitSignature` explicitly:
+Permits are auto-signed by default via the server's `/permits/prepare` endpoint. If you need manual control (pre-signed permits, multi-step workflows), pass a `PermitSignature` explicitly:
 
 ```ruby
-# sign_permit: convenience - auto-fetches nonce, converts amount to base units
-permit = wallet.sign_permit("0xRouterAddress...", 5.00, deadline: Time.now.to_i + 7200)
-tx = wallet.pay("0xRecipient...", 5.00, permit: permit)
-
-# sign_usdc_permit: full control - raw base units, explicit nonce
-permit = wallet.sign_usdc_permit(
-  "0xRouterAddress...",   # spender
-  5_000_000,              # value in base units (6 decimals)
-  Time.now.to_i + 3600,  # deadline
-  0,                      # nonce
-  usdc_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
-)
+permit = wallet.sign_permit("direct", 5.00)
 tx = wallet.pay("0xRecipient...", 5.00, permit: permit)
 ```
 
+Supported flows: `"direct"`, `"escrow"`, `"tab"`, `"stream"`, `"bounty"`, `"deposit"`.
+
 ## License
 
 MIT - see [LICENSE](LICENSE)

data/lib/remitmd/cli_signer.rb

@@ -71,7 +71,7 @@ module Remitmd
     #
     # 1. CLI binary found on PATH (via `which` / `where`)
     # 2. Meta file at ~/.remit/keys/default.meta (keychain — no password needed), OR
-    # 3. Keystore file at ~/.remit/keys/default.enc AND REMIT_KEY_PASSWORD env var set
+    # 3. Keystore file at ~/.remit/keys/default.enc AND REMIT_SIGNER_KEY env var set
     #
     # @param cli_path [String] path or name of the remit CLI binary
     # @return [Boolean]
@@ -90,7 +90,7 @@ module Remitmd
       keystore = File.join(keys_dir, "default.enc")
       return false unless File.exist?(keystore)
 
-      password = ENV["REMIT_KEY_PASSWORD"]
+      password = ENV["REMIT_SIGNER_KEY"] || ENV["REMIT_KEY_PASSWORD"]
       return false if password.nil? || password.empty?
 
       true

data/lib/remitmd/mock.rb

@@ -108,6 +108,10 @@ module Remitmd
     def sign(_message)
       "0x" + SecureRandom.hex(32) + SecureRandom.hex(32) + "1b"
     end
+
+    def sign_hash(_hash_bytes)
+      "0x" + SecureRandom.hex(32) + SecureRandom.hex(32) + "1b"
+    end
   end
 
   # ─── Internal: MockTransport ───────────────────────────────────────────────
@@ -135,6 +139,15 @@ module Remitmd
     def handle(method, path, b) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       case [method, path]
 
+      # Permits prepare (server-side permit signing)
+      in ["POST", "/permits/prepare"]
+        {
+          "hash"     => "0x#{SecureRandom.hex(32)}",
+          "value"    => ((b[:amount] || b["amount"]).to_f * 1_000_000).round.to_i,
+          "deadline" => Time.now.to_i + 3600,
+          "nonce"    => 0,
+        }
+
       # Contracts (for auto_permit)
       in ["GET", "/contracts"]
         {

data/lib/remitmd/signer.rb

@@ -23,6 +23,12 @@ module Remitmd
       raise NotImplementedError, "#{self.class}#sign is not implemented"
     end
 
+    # Sign a 32-byte hash (raw binary bytes). Returns 0x-prefixed 65-byte hex signature.
+    # Used by /permits/prepare and /x402/prepare flows.
+    def sign_hash(hash_bytes)
+      sign(hash_bytes)
+    end
+
     # The Ethereum address corresponding to the signing key (0x-prefixed).
     def address
       raise NotImplementedError, "#{self.class}#address is not implemented"

data/lib/remitmd/wallet.rb

@@ -5,11 +5,15 @@ require "bigdecimal/util"
 require "json"
 
 module Remitmd
-  # Known USDC contract addresses per chain (EIP-2612 compatible).
-  USDC_ADDRESSES = {
-    "base-sepolia" => "0x2d846325766921935f37d5b4478196d3ef93707c",
-    "base" => "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    "localhost" => "0x5FbDB2315678afecb367f032d93F642f64180aa3",
+  # Contract name -> flow name for /permits/prepare.
+  CONTRACT_TO_FLOW = {
+    "router"  => "direct",
+    "escrow"  => "escrow",
+    "tab"     => "tab",
+    "stream"  => "stream",
+    "bounty"  => "bounty",
+    "deposit" => "deposit",
+    "relayer" => "direct",
   }.freeze
 
   # Primary remit.md client. All payment operations are methods on RemitWallet.
@@ -89,7 +93,7 @@ module Remitmd
       unless key
         raise ArgumentError,
           "No signing method available. Either:\n" \
-          "  1. Install the remit CLI and set REMIT_KEY_PASSWORD:\n" \
+          "  1. Install the remit CLI and set REMIT_SIGNER_KEY:\n" \
           "     macOS:   brew install remit-md/tap/remit\n" \
           "     Windows: winget install remit-md.remit\n" \
           "     Linux:   curl -fsSL https://remit.md/install.sh | sh\n" \
@@ -346,86 +350,37 @@ module Remitmd
       @signer.sign(digest)
     end
 
-    # ─── EIP-2612 Permit ─────────────────────────────────────────────────────
+    # ─── EIP-2612 Permit (via /permits/prepare) ────────────────────────────
 
-    # Sign an EIP-2612 permit for USDC approval.
-    # Domain: name="USD Coin", version="2", chainId, verifyingContract=USDC address
-    # Type: Permit(address owner, address spender, uint256 value, uint256 nonce, uint256 deadline)
-    # @param spender [String] contract address that will be approved
-    # @param value [Integer] amount in USDC base units (6 decimals)
-    # @param deadline [Integer] permit deadline (Unix timestamp)
-    # @param nonce [Integer] current permit nonce for this wallet
-    # @param usdc_address [String, nil] override the USDC contract address
-    # @return [PermitSignature]
-    def sign_usdc_permit(spender, value, deadline, nonce = 0, usdc_address: nil)
-      usdc_addr = usdc_address || USDC_ADDRESSES[@chain_key]
-      if usdc_addr.nil? || usdc_addr.empty?
-        raise RemitError.new(
-          RemitError::INVALID_ADDRESS,
-          "No USDC address configured for chain #{@chain_key.inspect}. " \
-          "Valid chains: #{USDC_ADDRESSES.keys.join(", ")}",
-          context: { chain: @chain_key }
-        )
-      end
-      chain_id = @chain_id || ChainId::BASE_SEPOLIA
-
-      # Domain separator for USDC (EIP-2612)
-      domain_type_hash = keccak256_raw(
-        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
-      )
-      name_hash = keccak256_raw("USD Coin")
-      version_hash = keccak256_raw("2")
-      chain_id_enc = abi_uint256(chain_id)
-      contract_enc = abi_address(usdc_addr)
-
-      domain_data = domain_type_hash + name_hash + version_hash + chain_id_enc + contract_enc
-      domain_sep = keccak256_raw(domain_data)
-
-      # Permit struct hash
-      type_hash = keccak256_raw(
-        "Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"
-      )
-      owner_enc    = abi_address(address)
-      spender_enc  = abi_address(spender)
-      value_enc    = abi_uint256(value)
-      nonce_enc    = abi_uint256(nonce)
-      deadline_enc = abi_uint256(deadline)
-
-      struct_data = type_hash + owner_enc + spender_enc + value_enc + nonce_enc + deadline_enc
-      struct_hash = keccak256_raw(struct_data)
-
-      # EIP-712 digest
-      digest = keccak256_raw("\x19\x01".b + domain_sep + struct_hash)
-      sig_hex = @signer.sign(digest)
-
-      # Parse r, s, v from the 65-byte signature
-      sig_bytes = sig_hex.delete_prefix("0x")
-      r = "0x#{sig_bytes[0, 64]}"
-      s = "0x#{sig_bytes[64, 64]}"
-      v = sig_bytes[128, 2].to_i(16)
-
-      PermitSignature.new(value: value, deadline: deadline, v: v, r: r, s: s)
-    end
-
-    # Convenience: sign a USDC permit. Auto-fetches nonce, defaults deadline to 1 hour.
-    # @param spender [String] contract address to approve (e.g. router, escrow)
+    # Sign a USDC permit via the server's /permits/prepare endpoint.
+    #
+    # The server computes the EIP-712 hash, manages nonces, and resolves
+    # contract addresses. The SDK only signs the hash.
+    #
+    # @param flow [String] payment flow ("direct", "escrow", "tab", "stream", "bounty", "deposit")
     # @param amount [Numeric] amount in USDC (e.g. 5.0 for $5.00)
-    # @param deadline [Integer, nil] optional Unix timestamp; defaults to 1 hour from now
     # @return [PermitSignature]
-    def sign_permit(spender, amount, deadline: nil)
-      usdc_addr = USDC_ADDRESSES[@chain_key]
-      if usdc_addr.nil? || usdc_addr.empty?
-        raise RemitError.new(
-          RemitError::INVALID_ADDRESS,
-          "No USDC address configured for chain #{@chain_key.inspect}. " \
-          "Valid chains: #{USDC_ADDRESSES.keys.join(", ")}",
-          context: { chain: @chain_key }
-        )
-      end
-      nonce = fetch_permit_nonce(usdc_addr)
-      dl = deadline || (Time.now.to_i + 3600)
-      raw = (amount * 1_000_000).round.to_i
-      sign_usdc_permit(spender, raw, dl, nonce, usdc_address: usdc_addr)
+    def sign_permit(flow, amount)
+      data = @transport.post("/permits/prepare", {
+        flow: flow,
+        amount: amount.to_s,
+        owner: address
+      })
+
+      hash_hex = data["hash"]
+      hash_bytes = [hash_hex.delete_prefix("0x")].pack("H*")
+
+      sig = @signer.sign_hash(hash_bytes)
+      sig_hex = sig.start_with?("0x") ? sig[2..] : sig
+      r = "0x#{sig_hex[0, 64]}"
+      s = "0x#{sig_hex[64, 64]}"
+      v = sig_hex[128, 2].to_i(16)
+
+      PermitSignature.new(
+        value: data["value"].to_i,
+        deadline: data["deadline"].to_i,
+        v: v, r: r, s: s
+      )
     end
 
     # ─── Streams (Payment Streaming) ─────────────────────────────────────────
@@ -676,7 +631,7 @@ module Remitmd
       )
     end
 
-    # ─── EIP-712 helpers (used by sign_tab_charge / sign_usdc_permit) ─────
+    # ─── EIP-712 helpers (used by sign_tab_charge) ─────────────────────
 
     def keccak256_raw(data)
       Remitmd::Keccak.digest(data.b)
@@ -693,51 +648,22 @@ module Remitmd
 
     # ─── Permit helpers ──────────────────────────────────────────────────
 
-    # Fetch the EIP-2612 permit nonce from the API.
-    # @param usdc_address [String] the USDC contract address
-    # @return [Integer] current nonce
-    def fetch_permit_nonce(_usdc_address)
-      return 0 if @mock_mode
-
-      data = @transport.get("/status/#{address}")
-      nonce = data.is_a?(Hash) ? data["permit_nonce"] : nil
-      if nonce.nil?
-        raise RemitError.new(
-          RemitError::NETWORK_ERROR,
-          "permit_nonce not available from API for #{address}. " \
-          "Ensure the server supports the permit_nonce field in GET /api/v1/status.",
-          context: { address: address }
-        )
-      end
-      nonce.to_i
-    end
-
-    # Auto-sign a permit for the given contract type and amount.
-    # Returns nil on failure instead of raising, so callers can proceed without a permit.
+    # Internal: auto-sign a permit via /permits/prepare.
+    # Maps the contract name to a flow and calls sign_permit().
+    # Returns nil on failure so callers degrade gracefully.
     # @param contract [String] contract key - "router", "escrow", "tab", etc.
     # @param amount [Numeric] amount in USDC
     # @return [PermitSignature, nil]
     def auto_permit(contract, amount)
-      contracts = get_contracts
-      spender = contracts.send(contract.to_sym)
-      return nil unless spender
-
-      sign_permit(spender, amount)
+      flow = CONTRACT_TO_FLOW[contract]
+      unless flow
+        warn "[remitmd] unknown contract for permit: #{contract}"
+        return nil
+      end
+      sign_permit(flow, amount)
     rescue => e
       warn "[remitmd] auto-permit failed for #{contract} (amount=#{amount}): #{e.message}"
       nil
     end
-
-    # Spender contract mapping for auto_permit.
-    PERMIT_SPENDER = {
-      pay:                  :router,
-      create_escrow:        :escrow,
-      create_tab:           :tab,
-      create_stream:        :stream,
-      create_bounty:        :bounty,
-      place_deposit:        :deposit,
-      create_fund_link:     :relayer,
-      create_withdraw_link: :relayer,
-    }.freeze
   end
 end

data/lib/remitmd/x402_client.rb

@@ -26,22 +26,25 @@ module Remitmd
   # On receiving a 402, the client:
   # 1. Decodes the PAYMENT-REQUIRED header (base64 JSON)
   # 2. Checks the amount is within max_auto_pay_usdc
-  # 3. Builds and signs an EIP-3009 transferWithAuthorization
-  # 4. Base64-encodes the PAYMENT-SIGNATURE header
-  # 5. Retries the original request with payment attached
+  # 3. Calls /x402/prepare to get hash + authorization fields
+  # 4. Signs the hash
+  # 5. Base64-encodes the PAYMENT-SIGNATURE header
+  # 6. Retries the original request with payment attached
   #
   # @example
   #   signer = Remitmd::PrivateKeySigner.new("0x...")
-  #   client = Remitmd::X402Client.new(wallet: signer)
+  #   client = Remitmd::X402Client.new(wallet: signer, api_transport: transport)
   #   response = client.fetch("https://api.provider.com/v1/data")
   #
   class X402Client
     attr_reader :last_payment
 
-    # @param wallet [#sign, #address] a signer that can sign EIP-712 digests
+    # @param wallet [#sign_hash, #address] a signer that can sign raw hashes
+    # @param api_transport [#post] authenticated HTTP transport for calling /x402/prepare
     # @param max_auto_pay_usdc [Float] maximum USDC amount to auto-pay per request (default: 0.10)
-    def initialize(wallet:, max_auto_pay_usdc: 0.10)
+    def initialize(wallet:, api_transport: nil, max_auto_pay_usdc: 0.10)
       @wallet            = wallet
+      @api_transport     = api_transport
       @max_auto_pay_usdc = max_auto_pay_usdc
       @last_payment      = nil
     end
@@ -106,96 +109,44 @@ module Remitmd
         raise AllowanceExceededError.new(amount_usdc, @max_auto_pay_usdc)
       end
 
-      # 4. Parse chainId from CAIP-2 network string (e.g. "eip155:84532" -> 84532).
-      chain_id = required["network"].split(":")[1].to_i
-
-      # 5. Build EIP-3009 authorization fields.
-      now_secs     = Time.now.to_i
-      valid_before = now_secs + (required["maxTimeoutSeconds"] || 60).to_i
-      nonce_bytes  = SecureRandom.bytes(32)
-      nonce_hex    = "0x#{nonce_bytes.unpack1("H*")}"
-
-      # 6. Sign EIP-712 typed data for TransferWithAuthorization.
-      digest = eip3009_digest(
-        chain_id:     chain_id,
-        asset:        required["asset"],
-        from:         @wallet.address,
-        to:           required["payTo"],
-        value:        amount_base_units,
-        valid_after:  0,
-        valid_before: valid_before,
-        nonce_bytes:  nonce_bytes
-      )
-      signature = @wallet.sign(digest)
+      # 4. Call /x402/prepare to get the hash + authorization fields.
+      unless @api_transport
+        raise RemitError.new("SERVER_ERROR",
+          "x402 auto-pay requires an api_transport for calling /x402/prepare")
+      end
+
+      prepare_data = @api_transport.post("/x402/prepare", {
+        payment_required: raw,
+        payer: @wallet.address
+      })
+
+      # 5. Sign the hash.
+      hash_hex = prepare_data["hash"]
+      hash_bytes = [hash_hex.delete_prefix("0x")].pack("H*")
+      signature = @wallet.sign_hash(hash_bytes)
 
-      # 7. Build PAYMENT-SIGNATURE JSON payload.
+      # 6. Build PAYMENT-SIGNATURE JSON payload.
       payment_payload = {
         scheme:      required["scheme"],
         network:     required["network"],
         x402Version: 1,
         payload: {
-          signature:     signature,
+          signature: signature,
           authorization: {
-            from:        @wallet.address,
-            to:          required["payTo"],
-            value:       required["amount"],
-            validAfter:  "0",
-            validBefore: valid_before.to_s,
-            nonce:       nonce_hex,
+            from:        prepare_data["from"],
+            to:          prepare_data["to"],
+            value:       prepare_data["value"],
+            validAfter:  prepare_data["valid_after"] || prepare_data["validAfter"],
+            validBefore: prepare_data["valid_before"] || prepare_data["validBefore"],
+            nonce:       prepare_data["nonce"],
           },
         },
       }
       payment_header = Base64.strict_encode64(JSON.generate(payment_payload))
 
-      # 8. Retry with PAYMENT-SIGNATURE header.
+      # 7. Retry with PAYMENT-SIGNATURE header.
       new_headers = headers.merge("PAYMENT-SIGNATURE" => payment_header)
       make_request(uri, method, new_headers, body)
     end
-
-    # Compute the EIP-712 hash for EIP-3009 TransferWithAuthorization.
-    def eip3009_digest(chain_id:, asset:, from:, to:, value:, valid_after:, valid_before:, nonce_bytes:)
-      # Domain separator: USD Coin / version 2
-      domain_type_hash = keccak256(
-        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
-      )
-      name_hash     = keccak256("USD Coin")
-      version_hash  = keccak256("2")
-      chain_id_enc  = abi_uint256(chain_id)
-      contract_enc  = abi_address(asset)
-
-      domain_data      = domain_type_hash + name_hash + version_hash + chain_id_enc + contract_enc
-      domain_separator = keccak256(domain_data)
-
-      # TransferWithAuthorization struct hash
-      type_hash = keccak256(
-        "TransferWithAuthorization(address from,address to,uint256 value," \
-        "uint256 validAfter,uint256 validBefore,bytes32 nonce)"
-      )
-      struct_data = type_hash +
-                    abi_address(from) +
-                    abi_address(to) +
-                    abi_uint256(value) +
-                    abi_uint256(valid_after) +
-                    abi_uint256(valid_before) +
-                    nonce_bytes
-
-      struct_hash = keccak256(struct_data)
-
-      # Final EIP-712 hash
-      keccak256("\x19\x01" + domain_separator + struct_hash)
-    end
-
-    def keccak256(data)
-      Remitmd::Keccak.digest(data.b)
-    end
-
-    def abi_uint256(value)
-      [value.to_i.to_s(16).rjust(64, "0")].pack("H*")
-    end
-
-    def abi_address(addr)
-      hex = addr.to_s.delete_prefix("0x").rjust(64, "0")
-      [hex].pack("H*")
-    end
   end
 end

data/lib/remitmd.rb

@@ -26,5 +26,5 @@ require_relative "remitmd/x402_paywall"
 #   mock.was_paid?("0x0000000000000000000000000000000000000001", 1.00) # => true
 #
 module Remitmd
-  VERSION = "0.2.4"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remitmd
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - remit.md
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-28 00:00:00.000000000 Z
+date: 2026-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec