heph-forge 0.1.0b0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
heph_forge/__init__.py ADDED
@@ -0,0 +1,62 @@
1
+ """HEPH Forge Python SDK."""
2
+
3
+ from .client import Forge, MachineClient
4
+ from .eip712 import (
5
+ CHAIN_IDS,
6
+ DYNAMIC_FEE_FLAG,
7
+ PAYMENT_402_TYPES,
8
+ POOL_TICK_SPACING,
9
+ SWAP_INTENT_TYPES,
10
+ compute_machine_id,
11
+ compute_pool_id,
12
+ encode_hook_data,
13
+ get_heph_domain,
14
+ get_heph_facilitator_domain,
15
+ resolve_chain_id,
16
+ )
17
+ from .bundler import BundlerClient, BundlerError, UserOperationReverted, UserOperationTimeout
18
+ from .errors import (
19
+ ChainNotConfigured,
20
+ HephError,
21
+ InsufficientGasFunds,
22
+ MachineFrozenError,
23
+ RegistrationMismatch,
24
+ RpcError,
25
+ )
26
+ from .keystore import CallbackKeyStore, DevKeyStore, KeyStore, KeystoreError, is_production
27
+ from .userop import ENTRYPOINT_V07, UserOperation
28
+
29
+ __all__ = [
30
+ "Forge",
31
+ "MachineClient",
32
+ "KeyStore",
33
+ "DevKeyStore",
34
+ "compute_machine_id",
35
+ "compute_pool_id",
36
+ "encode_hook_data",
37
+ "get_heph_domain",
38
+ "get_heph_facilitator_domain",
39
+ "SWAP_INTENT_TYPES",
40
+ "PAYMENT_402_TYPES",
41
+ "CHAIN_IDS",
42
+ "DYNAMIC_FEE_FLAG",
43
+ "POOL_TICK_SPACING",
44
+ "resolve_chain_id",
45
+ "is_production",
46
+ "CallbackKeyStore",
47
+ "KeystoreError",
48
+ "BundlerClient",
49
+ "BundlerError",
50
+ "UserOperationReverted",
51
+ "UserOperationTimeout",
52
+ "UserOperation",
53
+ "ENTRYPOINT_V07",
54
+ "HephError",
55
+ "ChainNotConfigured",
56
+ "InsufficientGasFunds",
57
+ "MachineFrozenError",
58
+ "RegistrationMismatch",
59
+ "RpcError",
60
+ ]
61
+
62
+ __version__ = "0.1.0"
heph_forge/abis.py ADDED
@@ -0,0 +1,131 @@
1
+ """Minimal ABIs of the HEPH contracts + EntryPoint v0.7 used by the Python SDK.
2
+
3
+ Only the functions/events used by the SDK. Compatibility with the real contracts is verified by
4
+ `tests/test_integration_anvil.py` (real contracts on Anvil), not by assumption.
5
+ """
6
+
7
+ from typing import Any, Dict, List
8
+
9
+
10
+ def _fn(name: str, inputs: List[Dict[str, Any]], outputs: List[Dict[str, Any]], mutability: str = "view") -> Dict[str, Any]:
11
+ return {"type": "function", "name": name, "inputs": inputs, "outputs": outputs, "stateMutability": mutability}
12
+
13
+
14
+ def _p(type_: str, name: str = "", components: List[Dict[str, Any]] | None = None) -> Dict[str, Any]:
15
+ out: Dict[str, Any] = {"type": type_, "name": name}
16
+ if components is not None:
17
+ out["components"] = components
18
+ return out
19
+
20
+
21
+ POOL_KEY_COMPONENTS = [
22
+ _p("address", "currency0"),
23
+ _p("address", "currency1"),
24
+ _p("uint24", "fee"),
25
+ _p("int24", "tickSpacing"),
26
+ _p("address", "hooks"),
27
+ ]
28
+
29
+ SWAP_REQUEST_COMPONENTS = [
30
+ _p("tuple", "key", POOL_KEY_COMPONENTS),
31
+ _p("bool", "zeroForOne"),
32
+ _p("uint128", "amountIn"),
33
+ _p("uint128", "minAmountOut"),
34
+ _p("bytes", "hookData"),
35
+ ]
36
+
37
+ MACHINE_COMPONENTS = [
38
+ _p("address", "account"),
39
+ _p("address", "operator"),
40
+ _p("address", "signer"),
41
+ _p("bytes32", "attestationHash"),
42
+ _p("uint64", "registeredAt"),
43
+ _p("uint64", "lastActiveAt"),
44
+ _p("uint64", "lastViolationAt"),
45
+ _p("bool", "attestationValid"),
46
+ _p("bool", "frozen"),
47
+ ]
48
+
49
+ PACKED_USER_OP_COMPONENTS = [
50
+ _p("address", "sender"),
51
+ _p("uint256", "nonce"),
52
+ _p("bytes", "initCode"),
53
+ _p("bytes", "callData"),
54
+ _p("bytes32", "accountGasLimits"),
55
+ _p("uint256", "preVerificationGas"),
56
+ _p("bytes32", "gasFees"),
57
+ _p("bytes", "paymasterAndData"),
58
+ _p("bytes", "signature"),
59
+ ]
60
+
61
+ REGISTRY_ABI = [
62
+ _fn("machineIdOf", [_p("address", "account")], [_p("bytes32")]),
63
+ _fn("getMachine", [_p("bytes32", "machineId")], [_p("tuple", "", MACHINE_COMPONENTS)]),
64
+ _fn("tierOf", [_p("bytes32", "machineId")], [_p("uint8")]),
65
+ _fn("isFrozen", [_p("bytes32", "machineId")], [_p("bool")]),
66
+ _fn("dailySpent", [_p("bytes32", "machineId"), _p("uint64", "day")], [_p("uint256")]),
67
+ ]
68
+
69
+ HOOK_ABI = [
70
+ _fn("effectiveTierOf", [_p("bytes32", "machineId")], [_p("uint8")]),
71
+ ]
72
+
73
+ ROUTER_ABI = [
74
+ _fn("swap", [_p("tuple", "req", SWAP_REQUEST_COMPONENTS)], [_p("uint256", "amountOut")], "nonpayable"),
75
+ {
76
+ "type": "event",
77
+ "name": "MachineSwap",
78
+ "anonymous": False,
79
+ "inputs": [
80
+ {**_p("bytes32", "machineId"), "indexed": True},
81
+ {**_p("address", "account"), "indexed": True},
82
+ {**_p("address", "tokenIn"), "indexed": False},
83
+ {**_p("uint256", "amountIn"), "indexed": False},
84
+ {**_p("uint256", "amountOut"), "indexed": False},
85
+ {**_p("uint256", "protocolFee"), "indexed": False},
86
+ ],
87
+ },
88
+ ]
89
+
90
+ ERC20_ABI = [
91
+ _fn("balanceOf", [_p("address", "owner")], [_p("uint256")]),
92
+ _fn("decimals", [], [_p("uint8")]),
93
+ _fn("approve", [_p("address", "spender"), _p("uint256", "amount")], [_p("bool")], "nonpayable"),
94
+ ]
95
+
96
+ ACCOUNT_ABI = [
97
+ _fn("sessionKey", [], [_p("address")]),
98
+ _fn("owner", [], [_p("address")]),
99
+ _fn(
100
+ "executeBatch",
101
+ [_p("address[]", "dests"), _p("uint256[]", "values"), _p("bytes[]", "datas")],
102
+ [],
103
+ "nonpayable",
104
+ ),
105
+ ]
106
+
107
+ ENTRYPOINT_ABI = [
108
+ _fn("getNonce", [_p("address", "sender"), _p("uint192", "key")], [_p("uint256")]),
109
+ _fn("balanceOf", [_p("address", "account")], [_p("uint256")]),
110
+ _fn("getUserOpHash", [_p("tuple", "userOp", PACKED_USER_OP_COMPONENTS)], [_p("bytes32")]),
111
+ _fn(
112
+ "handleOps",
113
+ [_p("tuple[]", "ops", PACKED_USER_OP_COMPONENTS), _p("address", "beneficiary")],
114
+ [],
115
+ "nonpayable",
116
+ ),
117
+ {
118
+ "type": "event",
119
+ "name": "UserOperationEvent",
120
+ "anonymous": False,
121
+ "inputs": [
122
+ {**_p("bytes32", "userOpHash"), "indexed": True},
123
+ {**_p("address", "sender"), "indexed": True},
124
+ {**_p("address", "paymaster"), "indexed": True},
125
+ {**_p("uint256", "nonce"), "indexed": False},
126
+ {**_p("bool", "success"), "indexed": False},
127
+ {**_p("uint256", "actualGasCost"), "indexed": False},
128
+ {**_p("uint256", "actualGasUsed"), "indexed": False},
129
+ ],
130
+ },
131
+ ]
heph_forge/bundler.py ADDED
@@ -0,0 +1,76 @@
1
+ """ERC-4337 bundler JSON-RPC client (eth_sendUserOperation / eth_getUserOperationReceipt)."""
2
+
3
+ import time
4
+ from typing import Any, Dict, Optional
5
+
6
+ import requests
7
+
8
+
9
+ class BundlerError(Exception):
10
+ """The bundler rejected the UserOperation or is unreachable."""
11
+
12
+
13
+ class UserOperationTimeout(BundlerError):
14
+ """The UserOperation was sent but not confirmed within the time limit."""
15
+
16
+
17
+ class UserOperationReverted(BundlerError):
18
+ """The UserOperation landed on-chain but its execution failed (success == false)."""
19
+
20
+
21
+ class BundlerClient:
22
+ def __init__(self, url: str, timeout: float = 15.0) -> None:
23
+ if not url:
24
+ raise ValueError("bundler url is required")
25
+ self.url = url
26
+ self.timeout = timeout
27
+ self._id = 0
28
+
29
+ def _rpc(self, method: str, params: list) -> Any:
30
+ self._id += 1
31
+ try:
32
+ response = requests.post(
33
+ self.url,
34
+ json={"jsonrpc": "2.0", "id": self._id, "method": method, "params": params},
35
+ timeout=self.timeout,
36
+ )
37
+ except Exception as exc: # noqa: BLE001
38
+ raise BundlerError(f"Bundler is unreachable: {exc}") from exc
39
+
40
+ try:
41
+ body = response.json()
42
+ except Exception as exc: # noqa: BLE001
43
+ raise BundlerError(f"Bundler response is not JSON (HTTP {response.status_code})") from exc
44
+
45
+ if not isinstance(body, dict):
46
+ raise BundlerError("Invalid bundler response")
47
+ if body.get("error"):
48
+ err = body["error"]
49
+ message = err.get("message") if isinstance(err, dict) else str(err)
50
+ raise BundlerError(f"Bundler rejected {method}: {message}")
51
+ if response.status_code != 200:
52
+ raise BundlerError(f"Bundler replied with HTTP {response.status_code}")
53
+ return body.get("result")
54
+
55
+ def send_user_operation(self, user_op_rpc: Dict[str, str], entry_point: str) -> str:
56
+ """Sends a UserOperation; returns the userOpHash from the bundler."""
57
+ result = self._rpc("eth_sendUserOperation", [user_op_rpc, entry_point])
58
+ if not isinstance(result, str) or not result.startswith("0x"):
59
+ raise BundlerError("Bundler did not return a valid userOpHash")
60
+ return result
61
+
62
+ def get_user_operation_receipt(self, user_op_hash: str) -> Optional[Dict[str, Any]]:
63
+ result = self._rpc("eth_getUserOperationReceipt", [user_op_hash])
64
+ return result if isinstance(result, dict) else None
65
+
66
+ def wait_for_receipt(self, user_op_hash: str, timeout: float = 60.0, poll_interval: float = 1.0) -> Dict[str, Any]:
67
+ deadline = time.monotonic() + timeout
68
+ while True:
69
+ receipt = self.get_user_operation_receipt(user_op_hash)
70
+ if receipt is not None:
71
+ return receipt
72
+ if time.monotonic() >= deadline:
73
+ raise UserOperationTimeout(
74
+ f"UserOperation {user_op_hash} was not confirmed after {timeout:.0f} seconds"
75
+ )
76
+ time.sleep(poll_interval)