2n20 0.1.0__py3-none-any.whl

2n20-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: 2n20
+Version: 0.1.0
+Summary: Local trading-key setup and public connection checks for 2n20 creators
+Author: 2n20
+License-Expression: MIT
+Project-URL: Homepage, https://2n20.org
+Project-URL: Documentation, https://2n20.org/docs/quickstart
+Project-URL: Repository, https://github.com/2n20/2n20
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: annotated-types==0.8.0
+Requires-Dist: bitarray==3.11.0
+Requires-Dist: ckzg==2.1.8
+Requires-Dist: cytoolz==1.1.0
+Requires-Dist: eth-account==0.13.7
+Requires-Dist: eth-hash==0.8.0
+Requires-Dist: eth-keyfile==0.8.1
+Requires-Dist: eth-keys==0.8.0
+Requires-Dist: eth-rlp==3.0.0
+Requires-Dist: eth-typing==6.0.0
+Requires-Dist: eth-utils==6.0.0
+Requires-Dist: eth_abi==6.0.0
+Requires-Dist: hexbytes==2.0.0
+Requires-Dist: parsimonious==0.10.0
+Requires-Dist: pycryptodome==3.23.0
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: pydantic_core==2.46.5
+Requires-Dist: regex==2026.9.10
+Requires-Dist: rlp==5.0.0
+Requires-Dist: toolz==1.1.0
+Requires-Dist: typing-inspection==0.4.4
+Requires-Dist: typing_extensions==4.16.0
+Dynamic: license-file
+
+# 2n20 creator setup
+
+The official 2n20 CLI prepares trading-key consent on the computer or server
+where your existing strategy runs. It supplies public account configuration
+and read-only checks. You supply and run your own strategy in any language.
+
+Requires Python 3.10 or later on Linux, macOS or WSL. Run commands in your
+strategy's working directory with its Python environment activated.
+
+Copy the setup command from Step 2 of your vault page:
+
+```sh
+2n20 setup --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
+```
+
+The CLI verifies the chain, factory, deployed contract code, vault bindings,
+trading-account bindings, consent capability and next approval nonce from
+public contract reads. This release bundles the currently supported HyperEVM
+mainnet deployment. Other networks and unsupported deployments fail closed.
+Vault URLs can select only a vault address and network. They cannot override
+RPC endpoints or supply an approval contract, trading account or nonce.
+
+Setup creates a new directory with mode `700` under your current working
+directory. Use `--output <new-directory>` to choose its name. The parent must
+already exist. Setup never reuses an existing output directory.
+
+- `strategy.key`: your new private trading key, mode `600`. Keep it only on
+  your strategy machine. Never paste, import, upload, commit or log this file.
+- `consent.public.json`: a public signature, trading-key address, vault,
+  approval contract, nonce and expiry. Import or paste only this file into
+  Step 2 and approve it with your creator wallet.
+- `setup.public.json`: public recovery metadata used by `renew`.
+- `strategy.public.json`: public account settings for your existing strategy.
+
+Keep the directory and key when a network read fails. If consent expires
+(after one hour), or another approval changes its nonce, run on that same
+strategy machine:
+
+```sh
+2n20 renew --directory ./<your-setup-directory>
+```
+
+Renew retains the existing private key and writes a new uniquely named
+`consent.<time>-<random>.public.json`. Import that new public file. If the key
+has already been used, create a fresh setup in a new directory. Existing keys
+and files are never replaced. The app and contract recheck nonce and expiry
+when you approve.
+
+After Step 2 confirms trading access, get the public settings for Step 3:
+
+```sh
+2n20 config --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
+2n20 status --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet'
+```
+
+Use `tradingAccount` as your strategy's Hyperliquid account address. It is
+separate from the `vault` holding shares and the `approvalContract` your
+creator wallet calls. Load the private key locally using your strategy's own
+key configuration. The CLI does not load your existing strategy's secrets.
+
+Status checks the current public key approval, account binding and funding.
+Missing or inconsistent public evidence never counts as trading readiness.
+Exit code `0` means public trading access was verified, `2` means it is
+pending or unverified, and `1` means verification could not complete. This
+check does not prove your strategy is running. Run its own connection check
+before starting it. These commands submit no transactions, move no collateral
+and place no orders. Setup does not depend on temporary Hyperliquid balance or
+funding API availability.
+
+To check a public consent before importing it:
+
+```sh
+2n20 check-consent --vault 'https://2n20.org/vaults/<your-vault-address>?network=mainnet' --consent ./<your-setup-directory>/consent.public.json
+```
+
+## Reproducible development and release
+
+`requirements-release.txt` contains the reviewed, fully pinned build and
+runtime graph with registry SHA-256 hashes. `dependency-review.json` records
+its registry publication dates. All third-party release files were at least
+14 days old when reviewed on October 3, 2026. The wheel also pins the complete
+runtime graph to retain these reviewed versions for ordinary installs.
+The only underlying runtime library is `eth-account` and its dependencies;
+Hyperliquid's SDK is not required.
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install --require-hashes -r requirements-release.txt
+PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
+SOURCE_DATE_EPOCH=1790985600 .venv/bin/python scripts/build_release.py
+```
+
+The release script calls standard `python -m build --no-isolation`, verifies
+archive paths, and normalizes the source archive ownership, timestamps and
+gzip header. Keep `SOURCE_DATE_EPOCH` fixed for a release. Repeated builds from
+the same source and reviewed environment produce identical wheel and source
+archive bytes. Use `--outdir <directory>` to compare independent builds.
+
+Release trust anchors are copied from the repository's reviewed active
+`deployments/development.json`, never fetched as authority from a website.
+A supported deployment change requires reviewing and releasing the package.
+Publishing uses GitHub Actions OIDC Trusted Publishing with dedicated PyPI
+and TestPyPI environments, not stored API tokens. Maintainer release steps
+and publisher identities are in the repository operations runbook.

2n20-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+2n20-0.1.0.dist-info/licenses/LICENSE,sha256=uRP5-lYlB7ex3zJRPeYNhQ0q2rbG6ysuAEpJdTu0JOc,1061
+twon20/__init__.py,sha256=4Avfdk1iaw85amXWoXNppBKrBGi69HEGRbo5W8phEpw,90
+twon20/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+twon20/cli.py,sha256=5EndsssG24K2ICIyoph278bWEoYt0JEWFVfbySLUBh8,6729
+twon20/consent.py,sha256=9Xk7OrxT4V2We6OeaMOex9uLAv6DPT5dKeLdqD8w72c,7656
+twon20/deployments.json,sha256=u2rfHhnbA8ZKsIc9pE-X3GvPtwJh6vgZFzzinyOGp2k,2559
+twon20/discovery.py,sha256=KarkteZ3NwigI58Uj3V4prNfDfeDhpBjVGdzTdRfo4Y,12865
+twon20/errors.py,sha256=IWoo_iRU1-kWPp0vaEQkNfYXGhrMe0dP6l_Vpqz060A,246
+twon20/files.py,sha256=YA-bdQLX0fX-oPEJcCyo3M3Wk7DTh-tOn3zcKGB6-5I,6004
+twon20/rpc.py,sha256=zd4jRA0gASzGZnVXQkKh_p71smu-MFVGjk0IQu179m0,4218
+twon20/status.py,sha256=ygf0K1xx_oZm3S1bi-c3BYdVbkorfge4kc1yD2LYgvI,6148
+2n20-0.1.0.dist-info/METADATA,sha256=T8JZeV1vhAVgJomMEyYx2wPV82f9pfa8GeWJDtm_fgo,6535
+2n20-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+2n20-0.1.0.dist-info/entry_points.txt,sha256=twr9p6Zgg_8IStBm_Ve9prlgjkx1Ooo4KJtrwsRWlR4,41
+2n20-0.1.0.dist-info/top_level.txt,sha256=2TZ_7c_6HEB-6yjuIEJUWhdZTWRZgHMsuGimxfHfRd0,7
+2n20-0.1.0.dist-info/RECORD,,

2n20-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

2n20-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+2n20 = twon20.cli:main

2n20-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 2n20
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

2n20-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+twon20

twon20/__init__.py

@@ -0,0 +1,3 @@
+"""2n20 creator setup. No transaction or order submission APIs."""
+
+__version__ = "0.1.0"

twon20/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

twon20/cli.py

@@ -0,0 +1,116 @@
+"""The maintained 2n20 creator setup command."""
+
+import argparse
+import json
+import secrets
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from .consent import prepare, validate
+from .discovery import ZERO, discover
+from .errors import SetupError
+from .files import load_key, load_setup, new_output, open_output, read_public, retain_key
+from .rpc import Rpc
+from .status import status
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="2n20", description="Prepare local trading-key consent and verify public vault configuration. No transactions or trades are submitted.")
+    root.add_argument("--version", action="version", version=f"2n20 {__version__}")
+    commands = root.add_subparsers(dest="command", required=True)
+    setup = commands.add_parser("setup", help="Create a fresh private key locally and its public consent file")
+    setup.add_argument("--vault", required=True, help="The https://2n20.org/vaults/... link copied from Step 2")
+    setup.add_argument("--output", type=Path, help="A new private directory under an existing parent; defaults to a unique directory here")
+    setup.add_argument("--json", action="store_true", help="Print public result metadata as JSON")
+    renew = commands.add_parser("renew", help="Renew public consent using the key retained in your setup directory")
+    renew.add_argument("--directory", required=True, type=Path, help="The directory previously created by 2n20 setup")
+    renew.add_argument("--json", action="store_true")
+    for command, help_text in (("status", "Verify public trading access without placing an order"), ("config", "Print verified public configuration for your existing strategy"), ("check-consent", "Check a public consent file against fresh contract evidence")):
+        subparser = commands.add_parser(command, help=help_text)
+        subparser.add_argument("--vault", required=True)
+        if command == "check-consent":
+            subparser.add_argument("--consent", required=True, type=Path, help="Only the consent.public.json file")
+        subparser.add_argument("--json", action="store_true", help="Print public JSON (config always prints JSON)")
+    return root
+
+
+def setup(args) -> dict:
+    found = discover(args.vault)
+    rpc = Rpc(found.network)
+    output = new_output(found, args.output)
+    try:
+        wallet = retain_key(output, found)
+        consent = prepare(found, wallet, rpc)
+        public_path = output.json("consent.public.json", consent)
+        output.json("strategy.public.json", found.public())
+        return {"directory": str(output.path), "publicConsentFile": str(public_path), "tradingKey": wallet.address,
+                "expiresAt": int(consent["deadline"]), "nextAction": "Import only consent.public.json into Step 2 and approve with your creator wallet.",
+                "privateFile": "strategy.key stays on this machine. Never import, paste or upload it."}
+    except (SetupError, OSError, ValueError):
+        raise SetupError("SETUP_INCOMPLETE", f"Setup did not complete. Keep the directory {output.path}; any created private key was retained unchanged. Run 2n20 renew --directory '{output.path}' to retry consent generation. No transaction was submitted.") from None
+    finally:
+        output.close()
+
+
+def renew(args) -> dict:
+    output = open_output(args.directory)
+    try:
+        metadata = load_setup(output)
+        found = discover(metadata["vaultLink"])
+        wallet = load_key(output, metadata)
+        consent = prepare(found, wallet, Rpc(found.network))
+        name = f"consent.{int(time.time())}-{secrets.token_hex(4)}.public.json"
+        public_path = output.json(name, consent)
+        return {"directory": str(output.path), "publicConsentFile": str(public_path), "tradingKey": wallet.address,
+                "expiresAt": int(consent["deadline"]), "nextAction": "Import this new public file into Step 2. Older consent may be expired or stale.",
+                "privateFile": "The existing strategy.key was not changed. Keep it on this machine."}
+    finally:
+        output.close()
+
+
+def run(args) -> tuple[dict, int]:
+    if args.command == "setup":
+        return setup(args), 0
+    if args.command == "renew":
+        return renew(args), 0
+    found = discover(args.vault)
+    rpc = Rpc(found.network)
+    if args.command == "config":
+        if found.trading_account == ZERO:
+            raise SetupError("TRADING_ACCOUNT_PENDING", "Wait for vault funding to create the trading account, then run config again.")
+        return found.public() | {"nextAction": "Configure your existing strategy with tradingAccount as its account address and your local strategy.key as its signing key. Run your strategy's own connection check."}, 0
+    if args.command == "check-consent":
+        consent = validate(read_public(args.consent), found, rpc)
+        return {"valid": True, "vault": found.vault, "approvalContract": found.approval_contract,
+                "tradingKey": consent["key"], "nextApprovalNonce": consent["nonce"], "expiresAt": int(consent["deadline"]),
+                "nextAction": "Import this public consent into Step 2. The app and contract verify the nonce and expiry again before approval."}, 0
+    report = status(found, rpc)
+    return report, 0 if report["tradingAccessReady"] else 2
+
+
+def main(argv=None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        result, exit_code = run(args)
+        if args.json or args.command in ("config", "status"):
+            print(json.dumps(result, indent=2))
+        elif args.command in ("setup", "renew"):
+            print(f"Public consent file: {result['publicConsentFile']}")
+            print(result["privateFile"])
+            print(result["nextAction"])
+            print("Consent expires in one hour. If it expires or the nonce changes, run 2n20 renew --directory <your-setup-directory> here and import the new public file.")
+        else:
+            print("Public consent signature, vault, approval contract, nonce and expiry verified.")
+            print(result["nextAction"])
+        return exit_code
+    except SetupError as error:
+        print(f"{error.code}: {error.message}", file=sys.stderr)
+        return 1
+    except (OSError, ValueError, TypeError, KeyError):
+        print("SETUP_UNAVAILABLE: Setup could not complete. Keep any existing setup directory and key; no private material was displayed or overwritten. Check local permissions and retry. No transaction was submitted.", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("INTERRUPTED: Keep any created setup directory. Use 2n20 renew --directory <directory> to retry; existing keys were not overwritten.", file=sys.stderr)
+        return 130

twon20/consent.py

@@ -0,0 +1,99 @@
+"""Exact TradingKeyConsent EIP-712 format shared with the app and contract."""
+
+import re
+import time
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+from eth_utils import keccak
+from eth_keys.exceptions import BadSignature
+
+from .discovery import Discovery, UINT64_MAX, ZERO, address, code_bytes, verify_current
+from .errors import SetupError
+from .rpc import Rpc, parse_json
+
+SCHEMA = "2n20-trading-key-consent-v1"
+FIELDS = frozenset({"schema", "chainId", "venue", "vault", "key", "nonce", "deadline", "signature"})
+
+
+def typed_data(found: Discovery, key: str, nonce: int, deadline: int) -> dict:
+    return {"domain": {"name": "2n20 SDK venue", "version": "1", "chainId": found.anchor["chainId"], "verifyingContract": found.approval_contract},
+            "primaryType": "TradingKeyConsent",
+            "types": {"EIP712Domain": [{"name": "name", "type": "string"}, {"name": "version", "type": "string"}, {"name": "chainId", "type": "uint256"}, {"name": "verifyingContract", "type": "address"}],
+                      "TradingKeyConsent": [{"name": "vault", "type": "address"}, {"name": "key", "type": "address"}, {"name": "nonce", "type": "uint64"}, {"name": "deadline", "type": "uint64"}]},
+            "message": {"vault": found.vault, "key": key, "nonce": nonce, "deadline": deadline}}
+
+
+def digest(found: Discovery, key: str, nonce: int, deadline: int) -> bytes:
+    message = encode_typed_data(full_message=typed_data(found, key, nonce, deadline))
+    return keccak(b"\x19" + message.version + message.header + message.body)
+
+
+def verify_digest(found: Discovery, key: str, nonce: int, deadline: int, rpc: Rpc):
+    returned = rpc.words(found.approval_contract, "consentDigest(address,address,uint64,uint64)",
+                         [found.vault, key, nonce, deadline], found.fixed, 1)[0]
+    if returned != int.from_bytes(digest(found, key, nonce, deadline), "big"):
+        raise SetupError("CONSENT_FORMAT_MISMATCH", "The approval contract does not recognize this release's consent format.")
+
+
+def prepare(found: Discovery, wallet, rpc: Rpc, now: int | None = None) -> dict:
+    now = int(time.time()) if now is None else now
+    key = address(wallet.address)
+    if key in {ZERO, found.vault, found.owner, found.trading_account, found.requested_key}:
+        raise SetupError("KEY_NOT_FRESH", "The trading key is not a fresh independent account. Its private file remains unchanged.")
+    if code_bytes(rpc.call("eth_getCode", [key, found.fixed])) or rpc.words(found.approval_contract, "usedTradingKeys(address)", [key], found.fixed, 1) != [0]:
+        raise SetupError("KEY_ALREADY_USED", "This trading key has already been used. Keep it private and run setup in a new directory for a fresh key.")
+    nonce, deadline = found.nonce + 1, now + 3600
+    if deadline <= found.timestamp or deadline > found.timestamp + 86400:
+        raise SetupError("CLOCK_MISMATCH", "Check the machine clock before preparing consent.")
+    verify_digest(found, key, nonce, deadline, rpc)
+    signature = wallet.sign_message(encode_typed_data(full_message=typed_data(found, key, nonce, deadline))).signature.hex()
+    value = {"schema": SCHEMA, "chainId": found.anchor["chainId"], "venue": found.approval_contract,
+             "vault": found.vault, "key": wallet.address, "nonce": str(nonce), "deadline": str(deadline),
+             "signature": "0x" + signature.removeprefix("0x")}
+    current = verify_current(found, rpc)
+    if code_bytes(rpc.call("eth_getCode", [key, current])) or rpc.words(found.approval_contract, "usedTradingKeys(address)", [key], current, 1) != [0]:
+        raise SetupError("KEY_ALREADY_USED", "The trading key was used during verification. Keep the existing key private and create a fresh setup in a new directory.")
+    return value
+
+
+def validate(text: str, found: Discovery, rpc: Rpc, now: int | None = None) -> dict:
+    now = int(time.time()) if now is None else now
+    if len(text.encode("utf-8")) > 2000:
+        raise SetupError("INVALID_CONSENT", "Use only the small public consent JSON file, never strategy.key.")
+    try:
+        value = parse_json(text)
+    except ValueError:
+        raise SetupError("INVALID_CONSENT", "Select the public consent JSON file, never strategy.key.") from None
+    if not isinstance(value, dict) or set(value) != FIELDS or value.get("schema") != SCHEMA or type(value.get("chainId")) is not int or value["chainId"] != found.anchor["chainId"]:
+        raise SetupError("INVALID_CONSENT", "This public consent file does not match the supported schema and network.")
+    if address(value["vault"]) != found.vault or address(value["venue"]) != found.approval_contract:
+        raise SetupError("CONSENT_BINDING_MISMATCH", "This public consent is for a different vault or approval contract.")
+    key = address(value["key"])
+    if key in {found.vault, found.owner, found.trading_account, found.requested_key}:
+        raise SetupError("KEY_NOT_FRESH", "Consent must use a fresh independent trading key.")
+    if not isinstance(value["nonce"], str) or not re.fullmatch(r"[1-9][0-9]{0,19}", value["nonce"]) or int(value["nonce"]) != found.nonce + 1:
+        raise SetupError("STALE_NONCE", "The approval nonce changed. Run 2n20 renew --directory <your-setup-directory> on the strategy machine and import the new public file.")
+    if not isinstance(value["deadline"], str) or not re.fullmatch(r"[1-9][0-9]{0,19}", value["deadline"]) or int(value["deadline"]) > UINT64_MAX:
+        raise SetupError("INVALID_EXPIRY", "This consent has an invalid expiry. Renew it on the strategy machine.")
+    deadline = int(value["deadline"])
+    if deadline <= max(now, found.timestamp) or deadline > min(now, found.timestamp) + 86400:
+        raise SetupError("EXPIRED_CONSENT", "Consent expired or exceeds 24 hours. Run 2n20 renew --directory <your-setup-directory> on the strategy machine and import the new public file.")
+    if not isinstance(value["signature"], str) or not re.fullmatch(r"0x[0-9a-fA-F]{130}", value["signature"]):
+        raise SetupError("INVALID_SIGNATURE", "This consent has an invalid public signature.")
+    signature_bytes = bytes.fromhex(value["signature"][2:])
+    if signature_bytes[64] not in (27, 28) or not 0 < int.from_bytes(signature_bytes[32:64], "big") <= 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0:
+        raise SetupError("INVALID_SIGNATURE", "The signature must use the canonical contract ECDSA format.")
+    try:
+        recovered = Account.recover_message(encode_typed_data(full_message=typed_data(found, key, found.nonce + 1, deadline)), signature=value["signature"])
+    except (ValueError, TypeError, OverflowError, BadSignature):
+        raise SetupError("INVALID_SIGNATURE", "The consent signature could not be verified.") from None
+    if address(recovered) != key:
+        raise SetupError("INVALID_SIGNATURE", "The signature does not belong to this trading key.")
+    if code_bytes(rpc.call("eth_getCode", [key, found.fixed])) or rpc.words(found.approval_contract, "usedTradingKeys(address)", [key], found.fixed, 1) != [0]:
+        raise SetupError("KEY_ALREADY_USED", "This trading key cannot be approved again. Create a fresh setup in a new directory.")
+    verify_digest(found, key, found.nonce + 1, deadline, rpc)
+    current = verify_current(found, rpc)
+    if code_bytes(rpc.call("eth_getCode", [key, current])) or rpc.words(found.approval_contract, "usedTradingKeys(address)", [key], current, 1) != [0]:
+        raise SetupError("KEY_ALREADY_USED", "The trading key was used during verification. Keep the existing key private and create a fresh setup in a new directory.")
+    return value

twon20/deployments.json

@@ -0,0 +1,50 @@
+{
+  "generation": "7ed54c06-cda8-8dd2-9c18-e38e3bbaf4db",
+  "chainId": 999,
+  "genesisHash": "0xda486bf0d500d665b3ffd1e39ae55a99fd6e3a1f0115ea6b01abf080567a83c8",
+  "deploymentBlock": "47447750",
+  "deploymentHash": "0x7d7ef5a210384e9fa5b2826163edcb8879d8bc66582da8553d3c226a0a3508be",
+  "abiHash": "ee13cbb6c8012d933b340681d26831cc6bf11c56726f6b2c32f497af278f9c9c",
+  "codeHashes": {
+    "LocalVenue": "0xb852373f0fbf062a41b8793d96daa76e50240a8b7c1b5f00e8cb329da47ec336",
+    "MockUSDC": "0xa119f674d44072e257f162aee49c7aba9b7a04fe2e8c84fcefddb366ab6d40cd",
+    "PlatformController": "0x48a6c47e84648ac4fd936b4930eb3f540e1d06b59e1685975f6b8d45933e98be",
+    "ProtectedCollector": "0xb85e5d26df0d3e74743a359ceb2668f41dc4982b9ac60c1536fa91633fc34468",
+    "ProtectedTreasury": "0x3b5ec14524ddfb87277ea7839230d5822ab1c62ed8ff9146526aacc779598b87",
+    "Safe": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
+    "Vault": "0xcafbf2c5df3b85e47773cd4ee93821ad6d76fac4792c6ee51a089cb4b4c55ecd",
+    "VaultFactory": "0x8988a5c5815f908fbf98720513534d39af3fb0b9baabf531fa65cc3f835f58c3",
+    "VaultFeeModule": "0xb4842c40b1a8f0a5226375e9c729cbe8ead04434e73c6c58ce5024f48ae85a0e"
+  },
+  "contracts": {
+    "LocalVenue": "0xFB1613C44Ad39500254e0441ca47F7E679862782",
+    "MockUSDC": "0xb88339CB7199b77E23DB6E890353E22632Ba630f",
+    "PlatformController": "0x74bC4F5F60D2AaC4b17EFC2c0E65a9B307A693DE",
+    "ProtectedCollector": "0xF4015395a834d517753a965C38220C729174b990",
+    "ProtectedTreasury": "0x85012d3c96D257706F82B2683Af0A2c44fe8c386",
+    "Safe": "0x6D046A9f585541755081f0D424e97A924d8B95c8",
+    "Vault": "0xbB672914C1FA44708A71461d7647a7E8824aD8aa",
+    "VaultFactory": "0xA7014e4821cb9331D7CBc8e9b49c7F33632f61cf",
+    "VaultFeeModule": "0x2377b7ec9432830C2D23B4C003fea91c2E602c57"
+  },
+  "venue": {
+    "kind": "hypercore",
+    "address": "0xFB1613C44Ad39500254e0441ca47F7E679862782",
+    "model": "sdk",
+    "operator": "0x6D046A9f585541755081f0D424e97A924d8B95c8"
+  },
+  "profile": "development",
+  "artifacts": {
+    "LocalVenue": "DevelopmentSdkVenue",
+    "PlatformController": "DevelopmentPlatformController",
+    "ProtectedTreasury": "DevelopmentTreasury",
+    "Vault": "DevelopmentSdkVault",
+    "VaultFactory": "DevelopmentVaultFactory"
+  },
+  "owner": {
+    "kind": "eoa",
+    "address": "0x6D046A9f585541755081f0D424e97A924d8B95c8"
+  },
+  "classification": "development-only: EOA-owned controller, fixed-destination recovery, actor-restricted",
+  "registry": ".agents/hypercore-deployments.json#999:development-family-v6"
+}

twon20/discovery.py

@@ -0,0 +1,201 @@
+"""Discovery uses bundled release trust anchors and canonical public EVM reads.
+
+A vault URL selects only its address and a supported network. It cannot supply
+an RPC, approval contract, deployment, nonce or trading account.
+"""
+
+import json
+import re
+import time
+from dataclasses import dataclass
+from importlib.resources import files
+from urllib.parse import parse_qs, urlsplit
+
+from eth_utils import keccak
+
+from .errors import SetupError
+from .rpc import Rpc, integer
+
+ZERO = "0x" + "0" * 40
+HASH = re.compile(r"0x[0-9a-fA-F]{64}\Z")
+ADDRESS = re.compile(r"0x[0-9a-fA-F]{40}\Z")
+UINT64_MAX = 2 ** 64 - 1
+
+
+def address(value, allow_zero=False) -> str:
+    if not isinstance(value, str) or not ADDRESS.fullmatch(value) or not allow_zero and value.lower() == ZERO:
+        raise SetupError("INVALID_ADDRESS", "Use a valid nonzero public Ethereum address.")
+    return value.lower()
+
+
+def decoded_address(value: int, allow_zero=False) -> str:
+    if not 0 <= value < 2 ** 160:
+        raise SetupError("INVALID_CONTRACT_READ", "A contract returned an invalid address.")
+    return address(f"0x{value:040x}", allow_zero)
+
+
+def vault_link(value: str) -> tuple[str, str, str]:
+    try:
+        parsed = urlsplit(value)
+        query = parse_qs(parsed.query, keep_blank_values=True, strict_parsing=True) if parsed.query else {}
+    except ValueError:
+        raise SetupError("INVALID_VAULT_LINK", "Copy the vault link from https://2n20.org.") from None
+    if parsed.scheme != "https" or parsed.netloc != "2n20.org" or parsed.fragment or set(query) - {"network"}:
+        raise SetupError("INVALID_VAULT_LINK", "Copy the vault link from https://2n20.org. The link may contain only the network selector.")
+    if "network" in query and len(query["network"]) != 1:
+        raise SetupError("INVALID_VAULT_LINK", "Use one network selector in the vault link.")
+    match = re.fullmatch(r"/vaults/(0x[0-9a-fA-F]{40})/?", parsed.path)
+    if not match:
+        raise SetupError("INVALID_VAULT_LINK", "Copy the full vault page link from https://2n20.org.")
+    network = query.get("network", ["mainnet"])[0]
+    if network != "mainnet":
+        raise SetupError("UNSUPPORTED_NETWORK", "This release supports verified HyperEVM mainnet deployments only. Do not change networks to bypass this check.")
+    vault = address(match[1])
+    return vault, network, f"https://2n20.org/vaults/{vault}?network={network}"
+
+
+def trust_anchor(network: str) -> dict:
+    if network != "mainnet":
+        raise SetupError("UNSUPPORTED_NETWORK", "No reviewed deployment is bundled for this network.")
+    return json.loads(files("twon20").joinpath("deployments.json").read_text(encoding="utf-8"))
+
+
+def same_hash(value, expected: str) -> bool:
+    return isinstance(value, str) and bool(HASH.fullmatch(value)) and value.lower() == expected.lower()
+
+
+def block_identity(value: dict, now: int | None = None) -> tuple[int, str, int]:
+    if not isinstance(value, dict) or not isinstance(value.get("hash"), str) or not HASH.fullmatch(value["hash"]):
+        raise SetupError("INVALID_RPC_EVIDENCE", "The RPC did not provide a canonical block identity.")
+    number, timestamp = integer(value.get("number")), integer(value.get("timestamp"))
+    if now is not None and (timestamp > now + 5 or now - timestamp > 300):
+        raise SetupError("STALE_CHAIN", "The public chain snapshot is stale or your clock is incorrect. Check your clock and try again.")
+    return number, value["hash"].lower(), timestamp
+
+
+def code_bytes(value) -> bytes:
+    if not isinstance(value, str) or not re.fullmatch(r"0x(?:[0-9a-fA-F]{2})*", value):
+        raise SetupError("INVALID_CONTRACT_READ", "The RPC returned invalid contract code.")
+    return bytes.fromhex(value[2:])
+
+
+@dataclass(frozen=True)
+class Discovery:
+    vault: str
+    network: str
+    link: str
+    anchor: dict
+    owner: str
+    approval_contract: str
+    trading_account: str
+    requested_key: str
+    revocation_pending: bool
+    nonce: int
+    block_number: int
+    block_hash: str
+    timestamp: int
+    book: tuple
+    observation: tuple
+    key_status: tuple
+    lifecycle: int
+    pending_requests: int
+
+    @property
+    def fixed(self) -> dict:
+        return {"blockHash": self.block_hash, "requireCanonical": True}
+
+    def public(self) -> dict:
+        return {"schema": "2n20-strategy-config-v1", "network": self.network, "chainId": self.anchor["chainId"],
+                "vaultLink": self.link, "vault": self.vault, "approvalContract": self.approval_contract,
+                "tradingAccount": self.trading_account, "creatorWallet": self.owner,
+                "hyperliquidInfoUrl": "https://api.hyperliquid.xyz/info",
+                "hyperliquidExchangeUrl": "https://api.hyperliquid.xyz/exchange",
+                "requestedTradingKey": self.requested_key, "nextApprovalNonce": str(self.nonce + 1),
+                "blockNumber": str(self.block_number), "blockHash": self.block_hash,
+                "strategyKeyFile": "strategy.key", "strategySupplied": False}
+
+
+def discover(link: str, rpc: Rpc | None = None, now: int | None = None, anchor: dict | None = None) -> Discovery:
+    vault, network, canonical_link = vault_link(link)
+    anchor = anchor if anchor is not None else trust_anchor(network)
+    rpc = rpc if rpc is not None else Rpc(network)
+    chain_id = integer(rpc.call("eth_chainId", []))
+    if chain_id != anchor["chainId"] or chain_id != 999:
+        raise SetupError("WRONG_CHAIN", "The public RPC is on the wrong chain. No key was created.")
+    deployment_block = rpc.call("eth_getBlockByNumber", [hex(int(anchor["deploymentBlock"])), False])
+    if not isinstance(deployment_block, dict) or not same_hash(deployment_block.get("hash"), anchor["genesisHash"]) or integer(deployment_block.get("number")) != int(anchor["deploymentBlock"]):
+        raise SetupError("UNVERIFIED_DEPLOYMENT", "The deployment block does not match this release's reviewed trust anchor.")
+    receipt = rpc.call("eth_getTransactionReceipt", [anchor["deploymentHash"]])
+    if not isinstance(receipt, dict) or not same_hash(receipt.get("transactionHash"), anchor["deploymentHash"]) or not same_hash(receipt.get("blockHash"), anchor["genesisHash"]) or integer(receipt.get("status")) != 1 or integer(receipt.get("blockNumber")) != int(anchor["deploymentBlock"]) or address(receipt.get("contractAddress")) != address(anchor["contracts"]["VaultFactory"]):
+        raise SetupError("UNVERIFIED_DEPLOYMENT", "The factory deployment receipt does not match the reviewed deployment.")
+    current = rpc.call("eth_getBlockByNumber", ["latest", False])
+    number, block_hash, timestamp = block_identity(current, int(time.time()) if now is None else now)
+    fixed = {"blockHash": block_hash, "requireCanonical": True}
+    contracts = anchor["contracts"]
+    factory, controller, venue, implementation, asset = [address(contracts[name]) for name in ("VaultFactory", "PlatformController", "LocalVenue", "Vault", "MockUSDC")]
+    if anchor.get("venue", {}).get("model") != "sdk" or address(anchor["venue"]["address"]) != venue:
+        raise SetupError("UNSUPPORTED_DEPLOYMENT", "This release supports the reviewed SDK approval contracts only.")
+    for name in ("VaultFactory", "PlatformController", "LocalVenue", "Vault", "MockUSDC"):
+        code = code_bytes(rpc.call("eth_getCode", [contracts[name], fixed]))
+        if not code or "0x" + keccak(code).hex() != anchor["codeHashes"][name].lower():
+            raise SetupError("CONTRACT_CODE_MISMATCH", "Contract code does not match the reviewed release. No setup data was accepted.")
+    read = lambda to, signature, args=(), count=1: rpc.words(to, signature, list(args), fixed, count)
+    identity = lambda to, signature, args=(): decoded_address(read(to, signature, args)[0])
+    if identity(factory, "settings()") != controller or identity(controller, "factory()") != factory or identity(factory, "venue()") != venue or identity(factory, "asset()") != asset or identity(factory, "defaultImplementation()") != implementation:
+        raise SetupError("FACTORY_BINDING_MISMATCH", "The reviewed factory and controller bindings do not match.")
+    if read(controller, "isVault(address)", [vault]) != [1]:
+        raise SetupError("UNREGISTERED_VAULT", "This vault does not belong to the reviewed 2n20 factory.")
+    clone = bytes.fromhex("363d3d373d3d3d363d73" + implementation[2:] + "5af43d82803e903d91602b57fd5bf3")
+    if code_bytes(rpc.call("eth_getCode", [vault, fixed])) != clone:
+        raise SetupError("UNSUPPORTED_VAULT", "This vault does not use the reviewed vault implementation.")
+    if identity(vault, "venue()") != venue or identity(vault, "asset()") != asset or identity(venue, "asset()") != asset or identity(venue, "operator()") != address(anchor["venue"]["operator"]):
+        raise SetupError("VAULT_BINDING_MISMATCH", "The vault, approval contract and deployment bindings do not match.")
+    if read(venue, "tradingKeyVersion()") != [2]:
+        raise SetupError("UNSUPPORTED_CAPABILITY", "This approval contract does not support the required consent format.")
+    owner = identity(vault, "owner()")
+    core = decoded_address(read(venue, "coreAccountOf(address)", [vault])[0], True)
+    book = tuple(read(venue, "book(address)", [vault], 4))
+    observation = tuple(read(venue, "observationState(address)", [vault], 4))
+    key = read(venue, "tradingKeys(address)", [vault], 3)
+    key_status = tuple(read(venue, "tradingKeyStatus(address)", [vault], 4))
+    lifecycle = read(vault, "lifecycle()")[0]
+    pending_requests = read(vault, "pendingRequestCount()")[0]
+    if decoded_address(book[0], True) != core or book[1] not in (0, 1, 2, 3) or book[2] != observation[0] or any(item > UINT64_MAX for item in (book[2], observation[0], observation[1], observation[2], key[2], key_status[1])) or key[1] not in (0, 1) or lifecycle not in (0, 1, 2):
+        raise SetupError("ACCOUNT_BINDING_MISMATCH", "The public trading-account state is inconsistent.")
+    for position in (0, 2, 3):
+        decoded_address(key_status[position], True)
+    requested = decoded_address(key[0], True)
+    if key[2] == UINT64_MAX:
+        raise SetupError("NONCE_EXHAUSTED", "This vault cannot request another trading key.")
+    if core != ZERO:
+        if not code_bytes(rpc.call("eth_getCode", [core, fixed])) or identity(core, "vault()") != vault or identity(core, "venue()") != venue or identity(core, "asset()") != asset:
+            raise SetupError("ACCOUNT_BINDING_MISMATCH", "The trading account is not bound to this vault and approval contract.")
+    found = Discovery(vault, network, canonical_link, anchor, owner, venue, core, requested, bool(key[1]), key[2], number, block_hash, timestamp, book, observation, key_status, lifecycle, pending_requests)
+    verify_current(found, rpc, now)
+    return found
+
+
+def verify_current(found: Discovery, rpc: Rpc, now: int | None = None):
+    """Reject reorganizations and state changes before using public evidence."""
+    if integer(rpc.call("eth_chainId", [])) != found.anchor["chainId"]:
+        raise SetupError("CHAIN_CHANGED", "The chain changed during discovery. Try again.")
+    canonical = rpc.call("eth_getBlockByNumber", [hex(found.block_number), False])
+    if block_identity(canonical)[:2] != (found.block_number, found.block_hash):
+        raise SetupError("CHAIN_CHANGED", "The chain changed during discovery. Try again.")
+    head_number, head_hash, _ = block_identity(rpc.call("eth_getBlockByNumber", ["latest", False]), int(time.time()) if now is None else now)
+    if head_number < found.block_number:
+        raise SetupError("CHAIN_CHANGED", "The chain head moved backwards. Try again.")
+    fixed = {"blockHash": head_hash, "requireCanonical": True}
+    checks = [(found.vault, "venue()", [], [int(found.approval_contract, 16)]),
+              (found.vault, "owner()", [], [int(found.owner, 16)]),
+              (found.approval_contract, "tradingKeys(address)", [found.vault], [int(found.requested_key, 16), int(found.revocation_pending), found.nonce]),
+              (found.approval_contract, "book(address)", [found.vault], list(found.book)),
+              (found.approval_contract, "tradingKeyStatus(address)", [found.vault], list(found.key_status)),
+              (found.vault, "lifecycle()", [], [found.lifecycle]),
+              (found.vault, "pendingRequestCount()", [], [found.pending_requests])]
+    for target, signature, args, expected in checks:
+        if rpc.words(target, signature, args, fixed, len(expected)) != expected:
+            raise SetupError("STATE_CHANGED", "The vault state or approval nonce changed during verification. Try again before importing consent.")
+    if block_identity(rpc.call("eth_getBlockByNumber", [hex(head_number), False]))[:2] != (head_number, head_hash):
+        raise SetupError("CHAIN_CHANGED", "The chain changed during verification. Try again.")
+    return fixed

twon20/errors.py

@@ -0,0 +1,7 @@
+class SetupError(Exception):
+    """A safe public error. Never attach response bodies or key material."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message

twon20/files.py

@@ -0,0 +1,133 @@
+"""Private files are created exclusively and accessed through directory handles."""
+
+import json
+import os
+import re
+import secrets
+import stat
+from pathlib import Path
+
+from eth_account import Account
+
+from .discovery import Discovery, address
+from .errors import SetupError
+from .rpc import parse_json
+
+
+def secure_directory(path: Path) -> int:
+    if not all(hasattr(os, flag) for flag in ("O_NOFOLLOW", "O_DIRECTORY")) or not hasattr(os, "getuid"):
+        raise SetupError("UNSUPPORTED_FILESYSTEM", "Run setup on Linux, macOS or WSL with private file permissions.")
+    path = path.expanduser().absolute()
+    descriptor = os.open(path.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for part in path.parts[1:]:
+            following = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=descriptor)
+            os.close(descriptor)
+            descriptor = following
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+class Output:
+    def __init__(self, path: Path, descriptor: int):
+        self.path = path
+        self.descriptor = descriptor
+
+    def close(self):
+        os.close(self.descriptor)
+
+    def write(self, name: str, text: str):
+        descriptor = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=self.descriptor)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.fsync(self.descriptor)
+
+    def json(self, name: str, value: dict):
+        self.write(name, json.dumps(value, indent=2) + "\n")
+        return self.path / name
+
+    def read(self, name: str, limit: int) -> str:
+        descriptor = os.open(name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=self.descriptor)
+        with os.fdopen(descriptor, "r", encoding="utf-8") as handle:
+            info = os.fstat(handle.fileno())
+            if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
+                raise SetupError("UNSAFE_FILE_PERMISSIONS", "The setup file must be a regular file owned by you with mode 600. Do not share its private material.")
+            text = handle.read(limit + 1)
+            if len(text) > limit:
+                raise SetupError("INVALID_SETUP_FILE", "The setup file has an unexpected format. No private material was displayed.")
+            return text
+
+
+def open_output(path: Path) -> Output:
+    path = path.expanduser().absolute()
+    descriptor = secure_directory(path)
+    info = os.fstat(descriptor)
+    if info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) != 0o700:
+        os.close(descriptor)
+        raise SetupError("UNSAFE_DIRECTORY_PERMISSIONS", "The setup directory must be owned by you with mode 700.")
+    return Output(path, descriptor)
+
+
+def new_output(found: Discovery, path: Path | None = None) -> Output:
+    path = (path if path is not None else Path.cwd() / f"2n20-{found.vault[2:10]}-{secrets.token_hex(6)}").expanduser().absolute()
+    parent = secure_directory(path.parent)
+    try:
+        os.mkdir(path.name, mode=0o700, dir_fd=parent)
+        os.fsync(parent)
+    except FileExistsError:
+        raise SetupError("OUTPUT_EXISTS", "The output directory already exists. No key was read or overwritten. Use a new directory, or renew your existing setup with 2n20 renew --directory <directory>.") from None
+    finally:
+        os.close(parent)
+    return open_output(path)
+
+
+def retain_key(output: Output, found: Discovery):
+    wallet = Account.create()
+    output.json("setup.public.json", {"schema": "2n20-local-setup-v1", "vaultLink": found.link, "tradingKey": wallet.address})
+    output.write("strategy.key", wallet.key.hex().removeprefix("0x") + "\n")
+    return wallet
+
+
+def load_setup(output: Output):
+    try:
+        value = parse_json(output.read("setup.public.json", 2000))
+    except ValueError:
+        raise SetupError("INVALID_SETUP_FILE", "This directory does not contain a valid 2n20 setup record.") from None
+    if not isinstance(value, dict) or set(value) != {"schema", "vaultLink", "tradingKey"} or value["schema"] != "2n20-local-setup-v1" or not isinstance(value["vaultLink"], str):
+        raise SetupError("INVALID_SETUP_FILE", "This directory does not contain a valid 2n20 setup record.")
+    return value
+
+
+def load_key(output: Output, metadata: dict):
+    text = output.read("strategy.key", 128).strip()
+    if not re.fullmatch(r"[0-9a-fA-F]{64}", text):
+        raise SetupError("INVALID_PRIVATE_FILE", "The local key file has an unexpected format. No private material was displayed or changed.")
+    try:
+        wallet = Account.from_key(text)
+    except ValueError:
+        raise SetupError("INVALID_PRIVATE_FILE", "The local key file cannot be used. No private material was displayed or changed.") from None
+    if address(wallet.address) != address(metadata["tradingKey"]):
+        raise SetupError("KEY_RECORD_MISMATCH", "The private file does not match its public setup record. No files were changed.")
+    return wallet
+
+
+def read_public(path: Path) -> str:
+    path = path.expanduser().absolute()
+    if not path.name.endswith(".public.json"):
+        raise SetupError("PUBLIC_FILE_ONLY", "Select a consent.public.json file. Never provide strategy.key, environment files or wallet backups.")
+    parent = secure_directory(path.parent)
+    try:
+        descriptor = os.open(path.name, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=parent)
+        with os.fdopen(descriptor, "r", encoding="utf-8") as handle:
+            if not stat.S_ISREG(os.fstat(handle.fileno()).st_mode):
+                raise SetupError("PUBLIC_FILE_ONLY", "Select a regular public consent JSON file.")
+            text = handle.read(2001)
+            if len(text) > 2000:
+                raise SetupError("INVALID_CONSENT", "The public consent file exceeds the supported size.")
+            return text
+    finally:
+        os.close(parent)

twon20/rpc.py

@@ -0,0 +1,93 @@
+"""Bounded, read-only JSON transport with fixed service endpoints."""
+
+import json
+import re
+import urllib.error
+import urllib.request
+
+from eth_utils import keccak
+
+from .errors import SetupError
+
+RPC_URLS = {"mainnet": "https://rpc.hyperliquid.xyz/evm"}
+INFO_URLS = {"mainnet": "https://api.hyperliquid.xyz/info"}
+MAX_BYTES = 1_048_576
+
+
+def unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("Duplicate JSON field")
+        result[key] = value
+    return result
+
+
+def parse_json(raw):
+    return json.loads(raw, object_pairs_hook=unique_object)
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise SetupError("REDIRECT_REJECTED", "A public service redirected the request. No setup data was accepted.")
+
+
+def request_json(url: str, payload: dict):
+    request = urllib.request.Request(url, data=json.dumps(payload).encode("utf-8"),
+                                     headers={"Content-Type": "application/json", "User-Agent": "2n20-creator-cli/0.1.0"}, method="POST")
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=15) as response:
+            raw = response.read(MAX_BYTES + 1)
+            if len(raw) > MAX_BYTES:
+                raise SetupError("RESPONSE_TOO_LARGE", "The public service returned too much data. Try again later.")
+            return parse_json(raw)
+    except SetupError:
+        raise
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError):
+        raise SetupError("PUBLIC_READ_UNAVAILABLE", "Public network evidence is unavailable. Try again later; no transaction was submitted.") from None
+
+
+class Rpc:
+    METHODS = frozenset({"eth_chainId", "eth_getBlockByNumber", "eth_getTransactionReceipt", "eth_getCode", "eth_call"})
+
+    def __init__(self, network: str):
+        self.url = RPC_URLS[network]
+        self._id = 0
+
+    def call(self, method: str, params: list):
+        if method not in self.METHODS:
+            raise SetupError("READ_ONLY", "Only public read operations are supported.")
+        self._id += 1
+        response = request_json(self.url, {"jsonrpc": "2.0", "id": self._id, "method": method, "params": params})
+        if not isinstance(response, dict) or type(response.get("id")) is not int or response.get("id") != self._id or response.get("jsonrpc") != "2.0" or "error" in response or "result" not in response:
+            raise SetupError("RPC_UNAVAILABLE", "A required public contract read failed. Try again later; no transaction was submitted.")
+        return response["result"]
+
+    def words(self, to: str, signature: str, arguments: list, block: dict, count: int) -> list[int]:
+        data = "0x" + keccak(text=signature)[:4].hex() + "".join(word(argument) for argument in arguments)
+        result = self.call("eth_call", [{"to": to, "data": data}, block])
+        if not isinstance(result, str) or not re.fullmatch(r"0x[0-9a-fA-F]{" + str(count * 64) + r"}", result):
+            raise SetupError("CAPABILITY_UNAVAILABLE", "The deployment did not return the supported contract capabilities.")
+        try:
+            return [int(result[offset:offset + 64], 16) for offset in range(2, len(result), 64)]
+        except ValueError:
+            raise SetupError("INVALID_CONTRACT_READ", "The public contract returned invalid evidence.") from None
+
+
+def word(value) -> str:
+    number = int(value, 16) if isinstance(value, str) else value
+    if isinstance(number, bool) or not isinstance(number, int) or number < 0 or number >= 2 ** 256:
+        raise SetupError("INVALID_INPUT", "Invalid public contract argument.")
+    return f"{number:064x}"
+
+
+def integer(value) -> int:
+    if not isinstance(value, str) or not re.fullmatch(r"0x[0-9a-fA-F]{1,64}", value):
+        raise SetupError("INVALID_RPC_EVIDENCE", "The RPC returned invalid chain evidence.")
+    try:
+        result = int(value, 16)
+    except ValueError:
+        raise SetupError("INVALID_RPC_EVIDENCE", "The RPC returned invalid chain evidence.") from None
+    if result < 0:
+        raise SetupError("INVALID_RPC_EVIDENCE", "The RPC returned invalid chain evidence.")
+    return result

twon20/status.py

@@ -0,0 +1,93 @@
+"""Public account access checks. This does not exercise a strategy or submit orders."""
+
+import time
+from decimal import Decimal, InvalidOperation
+
+from .discovery import Discovery, ZERO, address, decoded_address, verify_current
+from .errors import SetupError
+from .rpc import INFO_URLS, Rpc, request_json
+
+
+def decimal(value) -> Decimal:
+    if not isinstance(value, str) or len(value) > 100:
+        raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid returned invalid public funding evidence.")
+    try:
+        result = Decimal(value)
+    except InvalidOperation:
+        raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid returned invalid public funding evidence.") from None
+    if not result.is_finite() or result < 0:
+        raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid returned invalid public funding evidence.")
+    return result
+
+
+def status(found: Discovery, rpc: Rpc, now: int | None = None, info=None) -> dict:
+    now = int(time.time()) if now is None else now
+    info = info if info is not None else lambda payload: request_json(INFO_URLS[found.network], payload)
+    result = found.public() | {"tradingAccessReady": False, "strategyConnectionTested": False,
+                              "checkedAt": now, "evidence": "unavailable", "reasons": []}
+    reasons = result["reasons"]
+    if found.trading_account == ZERO:
+        reasons.append("The trading account has not been created yet. Wait for vault funding on Step 2.")
+        return result
+    if found.requested_key == ZERO:
+        reasons.append("Import public consent into Step 2 and approve it with the creator wallet.")
+        return result
+    if found.lifecycle != 0 or found.book[1] != 0 or found.pending_requests or found.revocation_pending:
+        reasons.append("The vault has a pending operation, withdrawal, revocation or closed lifecycle.")
+    if decoded_address(found.key_status[0], True) != found.requested_key or decoded_address(found.key_status[2], True) != found.owner or found.key_status[1] <= now:
+        reasons.append("The approval contract has not confirmed current trading access.")
+    try:
+        role = info({"type": "userRole", "user": found.requested_key})
+        agents = info({"type": "extraAgents", "user": found.trading_account})
+        mode = info({"type": "userAbstraction", "user": found.trading_account})
+        spot = info({"type": "spotClearinghouseState", "user": found.trading_account})
+        perp = info({"type": "clearinghouseState", "user": found.trading_account, "dex": ""})
+        if not isinstance(role, dict) or role.get("role") != "agent" or not isinstance(role.get("data"), dict) or address(role["data"].get("user")) != found.trading_account:
+            reasons.append("Hyperliquid has not confirmed this key's trading-account binding.")
+        if not isinstance(agents, list) or len(agents) > 100:
+            raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid agent evidence is unavailable.")
+        seen = set()
+        matched = False
+        for agent in agents:
+            if not isinstance(agent, dict):
+                raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid agent evidence is unavailable.")
+            account = address(agent.get("address"))
+            expiry = agent.get("validUntil")
+            if account in seen or type(expiry) is not int or not isinstance(agent.get("name"), str):
+                raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid agent evidence is inconsistent.")
+            seen.add(account)
+            if account == found.requested_key and expiry > now * 1000:
+                matched = True
+        if not matched:
+            reasons.append("Hyperliquid has not confirmed an unexpired approval for this trading key.")
+        if mode != "disabled":
+            reasons.append("The trading account is not in the supported standard account mode.")
+        if not isinstance(spot, dict) or not isinstance(spot.get("balances"), list) or not isinstance(perp, dict) or not isinstance(perp.get("marginSummary"), dict) or type(perp.get("time")) is not int or not now * 1000 - 15_000 <= perp["time"] <= now * 1000 + 5000:
+            raise SetupError("INVALID_CORE_EVIDENCE", "Fresh Hyperliquid balance evidence is unavailable.")
+        usdc = Decimal(0)
+        seen_tokens = set()
+        for balance in spot["balances"]:
+            if not isinstance(balance, dict) or type(balance.get("token")) is not int or balance["token"] in seen_tokens:
+                raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid spot evidence is inconsistent.")
+            seen_tokens.add(balance["token"])
+            total, hold = decimal(balance.get("total")), decimal(balance.get("hold"))
+            if hold > total:
+                raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid spot evidence is inconsistent.")
+            if balance["token"] == 0:
+                if balance.get("coin") != "USDC":
+                    raise SetupError("INVALID_CORE_EVIDENCE", "Hyperliquid USDC evidence is inconsistent.")
+                usdc += total - hold
+        usdc += decimal(perp["marginSummary"].get("accountValue"))
+        if usdc <= 0:
+            reasons.append("No available USDC backing was verified in the supported trading account.")
+        if role != info({"type": "userRole", "user": found.requested_key}) or agents != info({"type": "extraAgents", "user": found.trading_account}) or mode != info({"type": "userAbstraction", "user": found.trading_account}):
+            raise SetupError("CORE_STATE_CHANGED", "Hyperliquid key evidence changed during verification. Check again.")
+        verify_current(found, rpc)
+        if int(time.time()) - now > 45:
+            raise SetupError("STALE_CORE_EVIDENCE", "Connection evidence expired during verification. Check again.")
+        result["evidence"] = "verified-public-reads"
+        result["availableUsdc"] = str(usdc)
+        result["tradingAccessReady"] = not reasons
+    except (SetupError, KeyError, TypeError, ValueError):
+        reasons.append("Public Hyperliquid evidence is unavailable or inconsistent. Readiness is unverified; check again later.")
+    return result