hypnex-forge 0.2.1__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.
@@ -0,0 +1,74 @@
1
+ """hypnex-forge — Python SDK for the Forge tool registry on Morpheus AI.
2
+
3
+ Forge is the Hypnex Labs tools marketplace for the Morpheus AI ecosystem
4
+ and the broader MCP (Model-Context-Protocol) world. Each tool listing on
5
+ the on-chain registry pays a one-time fee in MOR to Hypnex Labs.
6
+
7
+ Monetization notice:
8
+ This SDK routes all listing fees from `register()` calls to the Hypnex
9
+ Labs treasury (0x22B5C0075372E743042b2d62b3D254425Eb957D8). The
10
+ listing fee is configurable on-chain by the claim-admin (default 1
11
+ MOR per listing). The on-chain `pricePerCallWei` you set on a tool
12
+ is what END USERS pay you for calls; that revenue stays with the
13
+ tool owner (Phase 1 — Phase 3 will add on-chain per-call settlement
14
+ with a Hypnex protocol fee).
15
+
16
+ Quickstart (read-only):
17
+
18
+ from hypnex_forge import Forge
19
+
20
+ f = Forge(chain="arbitrum")
21
+ print(f.total_tools())
22
+ print(f.list_tools(0, 100))
23
+ print(f.get_listing_fee_wei()) # 10**18 = 1 MOR
24
+
25
+ Quickstart (with signer):
26
+
27
+ import os
28
+ from hypnex_forge import Forge
29
+
30
+ f = Forge(
31
+ chain="arbitrum",
32
+ rpc_url=os.environ["ETH_RPC_URL"],
33
+ private_key=os.environ["PRIVATE_KEY"],
34
+ )
35
+ tx = f.register(
36
+ namespace="myorg",
37
+ name="websearch",
38
+ mcp_uri="https://mcp.example.com/v1",
39
+ categories=["search", "data"],
40
+ price_per_call_wei=int(0.001 * 10**18), # users pay 0.001 MOR per call
41
+ )
42
+ # SDK auto-approves the listing fee, then submits register().
43
+ """
44
+
45
+ from ._constants import (
46
+ CHAIN_IDS,
47
+ DEFAULT_CHAIN,
48
+ DEFAULT_RELAYER_URL,
49
+ ESCROW_ADDRESSES,
50
+ FORGE_ADDRESSES,
51
+ MOR_ADDRESSES,
52
+ PUBLIC_RPCS,
53
+ )
54
+ from .escrow import Escrow, receipt_struct_hash
55
+ from .forge import Forge, Tool, category_tag, tool_id
56
+
57
+ __version__ = "0.2.1"
58
+
59
+ __all__ = [
60
+ "Forge",
61
+ "Escrow",
62
+ "Tool",
63
+ "category_tag",
64
+ "tool_id",
65
+ "receipt_struct_hash",
66
+ "CHAIN_IDS",
67
+ "DEFAULT_CHAIN",
68
+ "DEFAULT_RELAYER_URL",
69
+ "FORGE_ADDRESSES",
70
+ "ESCROW_ADDRESSES",
71
+ "MOR_ADDRESSES",
72
+ "PUBLIC_RPCS",
73
+ "__version__",
74
+ ]
hypnex_forge/_abi.py ADDED
@@ -0,0 +1,353 @@
1
+ """ABI for the ForgeToolRegistry contract."""
2
+
3
+ from __future__ import annotations
4
+
5
+ FORGE_ABI = [
6
+ {
7
+ "type": "function",
8
+ "name": "toolIdOf",
9
+ "stateMutability": "pure",
10
+ "inputs": [
11
+ {"name": "namespace", "type": "string"},
12
+ {"name": "name", "type": "string"},
13
+ ],
14
+ "outputs": [{"name": "", "type": "bytes32"}],
15
+ },
16
+ {
17
+ "type": "function",
18
+ "name": "register",
19
+ "stateMutability": "nonpayable",
20
+ "inputs": [
21
+ {"name": "namespace", "type": "string"},
22
+ {"name": "name", "type": "string"},
23
+ {"name": "mcpURI", "type": "string"},
24
+ {"name": "categories", "type": "bytes32[]"},
25
+ {"name": "pricePerCallWei", "type": "uint256"},
26
+ ],
27
+ "outputs": [{"name": "toolId", "type": "bytes32"}],
28
+ },
29
+ {
30
+ "type": "function",
31
+ "name": "updateTool",
32
+ "stateMutability": "nonpayable",
33
+ "inputs": [
34
+ {"name": "toolId", "type": "bytes32"},
35
+ {"name": "mcpURI", "type": "string"},
36
+ {"name": "pricePerCallWei", "type": "uint256"},
37
+ ],
38
+ "outputs": [],
39
+ },
40
+ {
41
+ "type": "function",
42
+ "name": "setCategories",
43
+ "stateMutability": "nonpayable",
44
+ "inputs": [
45
+ {"name": "toolId", "type": "bytes32"},
46
+ {"name": "categories", "type": "bytes32[]"},
47
+ ],
48
+ "outputs": [],
49
+ },
50
+ {
51
+ "type": "function",
52
+ "name": "deactivate",
53
+ "stateMutability": "nonpayable",
54
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
55
+ "outputs": [],
56
+ },
57
+ {
58
+ "type": "function",
59
+ "name": "reactivate",
60
+ "stateMutability": "nonpayable",
61
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
62
+ "outputs": [],
63
+ },
64
+ {
65
+ "type": "function",
66
+ "name": "transferOwnership",
67
+ "stateMutability": "nonpayable",
68
+ "inputs": [
69
+ {"name": "toolId", "type": "bytes32"},
70
+ {"name": "newOwner", "type": "address"},
71
+ ],
72
+ "outputs": [],
73
+ },
74
+ {
75
+ "type": "function",
76
+ "name": "getTool",
77
+ "stateMutability": "view",
78
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
79
+ "outputs": [
80
+ {
81
+ "name": "",
82
+ "type": "tuple",
83
+ "components": [
84
+ {"name": "owner", "type": "address"},
85
+ {"name": "name", "type": "string"},
86
+ {"name": "namespace", "type": "string"},
87
+ {"name": "mcpURI", "type": "string"},
88
+ {"name": "categories", "type": "bytes32[]"},
89
+ {"name": "pricePerCallWei", "type": "uint256"},
90
+ {"name": "isActive", "type": "bool"},
91
+ {"name": "createdAt", "type": "uint64"},
92
+ {"name": "updatedAt", "type": "uint64"},
93
+ ],
94
+ }
95
+ ],
96
+ },
97
+ {
98
+ "type": "function",
99
+ "name": "isRegistered",
100
+ "stateMutability": "view",
101
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
102
+ "outputs": [{"name": "", "type": "bool"}],
103
+ },
104
+ {
105
+ "type": "function",
106
+ "name": "totalTools",
107
+ "stateMutability": "view",
108
+ "inputs": [],
109
+ "outputs": [{"name": "", "type": "uint256"}],
110
+ },
111
+ {
112
+ "type": "function",
113
+ "name": "listTools",
114
+ "stateMutability": "view",
115
+ "inputs": [
116
+ {"name": "offset", "type": "uint256"},
117
+ {"name": "limit", "type": "uint256"},
118
+ ],
119
+ "outputs": [{"name": "page", "type": "bytes32[]"}],
120
+ },
121
+ {
122
+ "type": "function",
123
+ "name": "toolsOf",
124
+ "stateMutability": "view",
125
+ "inputs": [{"name": "owner", "type": "address"}],
126
+ "outputs": [{"name": "", "type": "bytes32[]"}],
127
+ },
128
+ {
129
+ "type": "function",
130
+ "name": "toolsInCategory",
131
+ "stateMutability": "view",
132
+ "inputs": [{"name": "category", "type": "bytes32"}],
133
+ "outputs": [{"name": "", "type": "bytes32[]"}],
134
+ },
135
+ {
136
+ "type": "function",
137
+ "name": "listingFee",
138
+ "stateMutability": "view",
139
+ "inputs": [],
140
+ "outputs": [{"name": "", "type": "uint256"}],
141
+ },
142
+ {
143
+ "type": "function",
144
+ "name": "feeToken",
145
+ "stateMutability": "view",
146
+ "inputs": [],
147
+ "outputs": [{"name": "", "type": "address"}],
148
+ },
149
+ {
150
+ "type": "function",
151
+ "name": "claimAdmin",
152
+ "stateMutability": "view",
153
+ "inputs": [],
154
+ "outputs": [{"name": "", "type": "address"}],
155
+ },
156
+ {
157
+ "type": "function",
158
+ "name": "setListingFee",
159
+ "stateMutability": "nonpayable",
160
+ "inputs": [{"name": "newFee", "type": "uint256"}],
161
+ "outputs": [],
162
+ },
163
+ ]
164
+
165
+
166
+ # --- Escrow ABI (Phase 3 — per-call settlement) ---
167
+ ESCROW_ABI = [
168
+ {
169
+ "type": "function",
170
+ "name": "deposit",
171
+ "stateMutability": "nonpayable",
172
+ "inputs": [
173
+ {"name": "toolId", "type": "bytes32"},
174
+ {"name": "amount", "type": "uint256"},
175
+ ],
176
+ "outputs": [],
177
+ },
178
+ {
179
+ "type": "function",
180
+ "name": "balanceOf",
181
+ "stateMutability": "view",
182
+ "inputs": [
183
+ {"name": "toolId", "type": "bytes32"},
184
+ {"name": "agent", "type": "address"},
185
+ ],
186
+ "outputs": [{"name": "", "type": "uint256"}],
187
+ },
188
+ {
189
+ "type": "function",
190
+ "name": "toolRevenue",
191
+ "stateMutability": "view",
192
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
193
+ "outputs": [{"name": "", "type": "uint256"}],
194
+ },
195
+ {
196
+ "type": "function",
197
+ "name": "treasuryRevenue",
198
+ "stateMutability": "view",
199
+ "inputs": [],
200
+ "outputs": [{"name": "", "type": "uint256"}],
201
+ },
202
+ {
203
+ "type": "function",
204
+ "name": "withdrawTool",
205
+ "stateMutability": "nonpayable",
206
+ "inputs": [
207
+ {"name": "toolId", "type": "bytes32"},
208
+ {"name": "to", "type": "address"},
209
+ ],
210
+ "outputs": [],
211
+ },
212
+ {
213
+ "type": "function",
214
+ "name": "withdrawTreasury",
215
+ "stateMutability": "nonpayable",
216
+ "inputs": [{"name": "to", "type": "address"}],
217
+ "outputs": [],
218
+ },
219
+ {
220
+ "type": "function",
221
+ "name": "agentRequestWithdraw",
222
+ "stateMutability": "nonpayable",
223
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
224
+ "outputs": [],
225
+ },
226
+ {
227
+ "type": "function",
228
+ "name": "agentExecuteWithdraw",
229
+ "stateMutability": "nonpayable",
230
+ "inputs": [
231
+ {"name": "toolId", "type": "bytes32"},
232
+ {"name": "to", "type": "address"},
233
+ ],
234
+ "outputs": [],
235
+ },
236
+ {
237
+ "type": "function",
238
+ "name": "setSigner",
239
+ "stateMutability": "nonpayable",
240
+ "inputs": [
241
+ {"name": "toolId", "type": "bytes32"},
242
+ {"name": "newSigner", "type": "address"},
243
+ ],
244
+ "outputs": [],
245
+ },
246
+ {
247
+ "type": "function",
248
+ "name": "signerOf",
249
+ "stateMutability": "view",
250
+ "inputs": [{"name": "toolId", "type": "bytes32"}],
251
+ "outputs": [{"name": "", "type": "address"}],
252
+ },
253
+ {
254
+ "type": "function",
255
+ "name": "lastPeriodId",
256
+ "stateMutability": "view",
257
+ "inputs": [
258
+ {"name": "toolId", "type": "bytes32"},
259
+ {"name": "agent", "type": "address"},
260
+ ],
261
+ "outputs": [{"name": "", "type": "uint256"}],
262
+ },
263
+ {
264
+ "type": "function",
265
+ "name": "withdrawUnlockAt",
266
+ "stateMutability": "view",
267
+ "inputs": [
268
+ {"name": "toolId", "type": "bytes32"},
269
+ {"name": "agent", "type": "address"},
270
+ ],
271
+ "outputs": [{"name": "", "type": "uint64"}],
272
+ },
273
+ {
274
+ "type": "function",
275
+ "name": "protocolFeeBps",
276
+ "stateMutability": "view",
277
+ "inputs": [],
278
+ "outputs": [{"name": "", "type": "uint256"}],
279
+ },
280
+ {
281
+ "type": "function",
282
+ "name": "relayer",
283
+ "stateMutability": "view",
284
+ "inputs": [],
285
+ "outputs": [{"name": "", "type": "address"}],
286
+ },
287
+ {
288
+ "type": "function",
289
+ "name": "claimAdmin",
290
+ "stateMutability": "view",
291
+ "inputs": [],
292
+ "outputs": [{"name": "", "type": "address"}],
293
+ },
294
+ {
295
+ "type": "function",
296
+ "name": "settle",
297
+ "stateMutability": "nonpayable",
298
+ "inputs": [
299
+ {"name": "toolId", "type": "bytes32"},
300
+ {"name": "agent", "type": "address"},
301
+ {"name": "callCount", "type": "uint256"},
302
+ {"name": "periodId", "type": "uint256"},
303
+ {"name": "receiptSignature", "type": "bytes"},
304
+ ],
305
+ "outputs": [],
306
+ },
307
+ {
308
+ "type": "function",
309
+ "name": "quoteSettle",
310
+ "stateMutability": "view",
311
+ "inputs": [
312
+ {"name": "toolId", "type": "bytes32"},
313
+ {"name": "callCount", "type": "uint256"},
314
+ ],
315
+ "outputs": [
316
+ {"name": "totalCost", "type": "uint256"},
317
+ {"name": "toolPayout", "type": "uint256"},
318
+ {"name": "protocolFee", "type": "uint256"},
319
+ ],
320
+ },
321
+ ]
322
+
323
+
324
+ # --- minimal ERC-20 ABI for the MOR fee token. ---
325
+ ERC20_ABI = [
326
+ {
327
+ "type": "function",
328
+ "name": "approve",
329
+ "stateMutability": "nonpayable",
330
+ "inputs": [
331
+ {"name": "spender", "type": "address"},
332
+ {"name": "amount", "type": "uint256"},
333
+ ],
334
+ "outputs": [{"name": "", "type": "bool"}],
335
+ },
336
+ {
337
+ "type": "function",
338
+ "name": "allowance",
339
+ "stateMutability": "view",
340
+ "inputs": [
341
+ {"name": "owner", "type": "address"},
342
+ {"name": "spender", "type": "address"},
343
+ ],
344
+ "outputs": [{"name": "", "type": "uint256"}],
345
+ },
346
+ {
347
+ "type": "function",
348
+ "name": "balanceOf",
349
+ "stateMutability": "view",
350
+ "inputs": [{"name": "account", "type": "address"}],
351
+ "outputs": [{"name": "", "type": "uint256"}],
352
+ },
353
+ ]
@@ -0,0 +1,86 @@
1
+ """Hypnex Forge constants.
2
+
3
+ Forge is the paid tool registry — Phase 1 of the MRC 60 tools marketplace.
4
+ Each `register()` call costs `listingFee` MOR (default 1 MOR), forwarded
5
+ directly to the Hypnex Labs treasury inside the same tx.
6
+
7
+ Reference Solidity source:
8
+ projects/hypnex/registry-contracts/contracts/ForgeToolRegistry.sol
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ # --- Forge contract addresses per chain ---
14
+ # Filled in after deploy. None means "not yet deployed on that chain."
15
+ FORGE_ADDRESSES: dict[str, str | None] = {
16
+ "arbitrum": "0xa08ca3C2519DA71e923AD331AFE2989a99f013D2", # deployed 2026-05-09
17
+ "base": "0x0c617b36E628b9BE689E3c55Ec901ebDBB8B45aC", # deployed 2026-05-09
18
+ "ethereum": None,
19
+ "base-sepolia": None,
20
+ }
21
+
22
+ # --- ForgeEscrow (Phase 3) addresses per chain ---
23
+ # Filled in after deploy. None means "not yet deployed on that chain."
24
+ ESCROW_ADDRESSES: dict[str, str | None] = {
25
+ "arbitrum": "0x88E32F332A5140Af16c6273d8131bC84BC089Da5", # deployed 2026-05-09
26
+ "base": "0xCC258a7BBF361fd824e87D4b3C0D394De6Fd454F", # deployed 2026-05-09
27
+ "ethereum": None,
28
+ "base-sepolia": None,
29
+ }
30
+
31
+ DEFAULT_CHAIN = "arbitrum"
32
+
33
+ # MOR token (ERC-20) per chain — used as the listing-fee token.
34
+ MOR_ADDRESSES: dict[str, str | None] = {
35
+ "arbitrum": "0x092bAaDB7DEf4C3981454dD9c0A0D7FF07bCFc86",
36
+ "base": "0x7431aDa8a591C955a994a21710752EF9b882b8e3",
37
+ "ethereum": "0xcBB8f1BDA10b9696c57E13BC128Fe674769DCEc0",
38
+ "base-sepolia": None,
39
+ }
40
+
41
+ PUBLIC_RPCS: dict[str, tuple[str, ...]] = {
42
+ "base": (
43
+ "https://mainnet.base.org",
44
+ "https://base-rpc.publicnode.com",
45
+ "https://base.llamarpc.com",
46
+ ),
47
+ "arbitrum": (
48
+ "https://arb1.arbitrum.io/rpc",
49
+ "https://arbitrum-one-rpc.publicnode.com",
50
+ "https://arbitrum.llamarpc.com",
51
+ ),
52
+ "ethereum": (
53
+ "https://ethereum-rpc.publicnode.com",
54
+ "https://eth.merkle.io",
55
+ "https://eth.llamarpc.com",
56
+ ),
57
+ "base-sepolia": (
58
+ "https://sepolia.base.org",
59
+ ),
60
+ }
61
+
62
+ CHAIN_IDS: dict[str, int] = {
63
+ "ethereum": 1,
64
+ "base": 8453,
65
+ "arbitrum": 42161,
66
+ "base-sepolia": 84532,
67
+ }
68
+
69
+ PROBE_CALLDATA = "0x70a082310000000000000000000000000000000000000000000000000000000000000000"
70
+ PROBE_ADDRESS_BY_CHAIN: dict[str, str] = {
71
+ "ethereum": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
72
+ "base": "0x4200000000000000000000000000000000000006",
73
+ "arbitrum": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
74
+ "base-sepolia": "0x4200000000000000000000000000000000000006",
75
+ }
76
+
77
+ # Environment variables
78
+ ENV_FORGE_ADDRESS = "HYPNEX_FORGE_ADDRESS"
79
+ ENV_ESCROW_ADDRESS = "HYPNEX_FORGE_ESCROW_ADDRESS"
80
+ ENV_FORGE_CHAIN = "HYPNEX_FORGE_CHAIN"
81
+ ENV_RPC = "HYPNEX_FORGE_RPC_URL"
82
+ ENV_PRIVATE_KEY = "PRIVATE_KEY"
83
+ ENV_RELAYER_URL = "HYPNEX_FORGE_RELAYER_URL"
84
+
85
+ # Default Hypnex relayer endpoint (Phase 3 batched settlement).
86
+ DEFAULT_RELAYER_URL = "https://relayer.hypnex.xyz"