hypnex-staking 0.1.0__tar.gz

hypnex_staking-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+venv/
+env/
+
+# --- Node / TypeScript ---
+node_modules/
+*.tsbuildinfo
+.npm/
+.yarn/
+.pnpm-store/
+.parcel-cache/
+
+# --- Next.js (apps/stake) ---
+.next/
+out/
+.vercel/
+
+# --- Wrangler / Cloudflare ---
+.wrangler/
+
+# --- Foundry (registry-contracts) ---
+forge-cache/
+broadcast/
+
+# --- Editor / OS ---
+.idea/
+.vscode/
+.DS_Store
+*.swp
+*.swo
+*~
+
+# --- Local secrets — never commit ---
+.env
+.env.*
+!.env.example
+.env.local
+.env.production
+
+# --- Log + tmp ---
+*.log
+logs/
+tmp/
+
+# --- Build outputs in apps/bench ---
+apps/bench/out/
+
+# --- Generated bench data is committed (audit trail) but local runs aren't ---
+python-bench/data/*.jsonl
+
+# Claude Code session artifacts — never commit
+.claude/

hypnex_staking-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: hypnex-staking
+Version: 0.1.0
+Summary: On-chain staking helpers for the Morpheus AI capital pool. Wraps DepositPool.stake() with referrer support (MRC 73 unlocked-MOR rewards).
+Project-URL: Homepage, https://hypnex.xyz
+Project-URL: Documentation, https://docs.hypnex.xyz/staking
+Project-URL: Repository, https://github.com/hypnex-labs/hypnex
+Project-URL: Issues, https://github.com/hypnex-labs/hypnex/issues
+Author: Hypnex Labs
+License: MIT
+Keywords: aave,defi,ethereum,mor,morpheus,onchain,referral,staking,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: web3<8.0,>=6.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hypnex-staking (Python)
+
+On-chain helpers for the **Morpheus AI capital pool** on Ethereum mainnet. Wraps `DepositPool.stake()` and `claimReferrerTier()` so a Python developer can stake stETH/USDC/USDT/wBTC and capture **MRC 73 unlocked-MOR referral rewards**.
+
+```bash
+pip install hypnex-staking
+```
+
+## Why this exists
+
+Morpheus's `app.mor.org` UI requires AWS Cognito email signup. The capital pool's on-chain interface is wallet-native and supports referrer attribution, but no Python tooling exists for it. This package fills that gap.
+
+The single most under-marketed mechanic: **referral MOR is unlocked, while own-stake MOR is delayed 90 days** (MRC 73 vs MRC 46). Refer once, earn liquid MOR for as long as the referee stays staked.
+
+## Quickstart
+
+### Read-only (no key needed)
+
+```python
+from hypnex_staking import Staker
+
+s = Staker()  # public RPC, no signer
+
+# Inspect the live tier table
+for tier in s.get_referrer_tiers("USDC"):
+    print(tier)
+
+# Look up an existing position
+print(s.get_position("0xSomeAddress...", "USDC"))
+
+# Look up someone's referrer data
+print(s.get_referrer_data("0xReferrer...", "USDC"))
+```
+
+### With a signer (moves real funds)
+
+```python
+import os
+from hypnex_staking import Staker
+
+s = Staker(
+    rpc_url=os.environ["ETH_RPC_URL"],
+    private_key=os.environ["PRIVATE_KEY"],
+    default_referrer="0xYourHypnexLabsAddress",  # or set HYPNEX_REFERRER env
+)
+
+# Always dry-run first — returns calldata, doesn't broadcast
+print(s.stake("USDC", amount=1000, claim_lock_end=0, dry_run=True))
+
+# When ready, drop dry_run for the real tx
+tx = s.stake("USDC", amount=1000, claim_lock_end=0)
+print("submitted:", tx)
+```
+
+### Claim accumulated MRC 73 unlocked-MOR
+
+```python
+# Per MRC 73, this MOR has no 90-day lockup — claimable immediately.
+tx = s.claim_referrer_rewards("USDC")
+```
+
+## Verified contracts (Ethereum mainnet)
+
+| Contract | Address |
+|---|---|
+| USDC DepositPool | `0x6cCE082851Add4c535352f596662521B4De4750E` |
+| USDT DepositPool | `0x3B51989212BEdaB926794D6bf8e9E991218cf116` |
+| wBTC DepositPool | `0xdE283F8309Fd1AA46c95d299f6B8310716277A42` |
+| wETH DepositPool | `0x9380d72aBbD6e0Cc45095A2Ef8c2CA87d77Cb384` |
+| DistributorV2 | `0xDf1AC1AC255d91F5f4B1E3B4Aef57c5350F64C7A` |
+| ChainLinkDataConsumer | `0xd182263d06FDC463c96190005D6359CC3d3Bbc5e` |
+
+Sourced from `MorpheusAIs/SmartContracts` v7 deploy script — verified against the on-chain bytecode by `tests/test_read_only.py`.
+
+## Public API
+
+```
+Staker(w3=..., rpc_url=..., account=..., private_key=..., default_referrer=...)
+
+# read (no signer)
+.get_pool_address(asset) -> str
+.get_token_address(asset) -> str
+.get_decimals(asset) -> int
+.get_position(address, asset) -> Position
+.get_referrer_data(referrer, asset) -> ReferrerData
+.get_referrer_tiers(asset) -> list[ReferrerTier]
+.quote_tier(asset, virtual_amount_staked) -> ReferrerTier | None
+
+# write (signer required)
+.approve(asset, amount, dry_run=False) -> str (tx hash)
+.stake(asset, amount, claim_lock_end=0, referrer=None, auto_approve=True, dry_run=False) -> str
+.claim_referrer_rewards(asset, receiver=None, layerzero_fee_wei=0, dry_run=False) -> str
+```
+
+`asset` is one of `"USDC" | "USDT" | "WBTC" | "WETH"`.
+
+## Environment variables
+
+- `ETH_RPC_URL` — Ethereum mainnet RPC (free public default works for reads)
+- `PRIVATE_KEY` — for write methods only
+- `HYPNEX_REFERRER` — default referrer address (override per-call with `referrer=`)
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest                  # read-only mainnet smoke tests, no key needed
+```
+
+For write-method tests, run a local Anvil fork (`anvil --fork-url $ETH_RPC_URL`) and set `ETH_RPC_URL=http://localhost:8545` plus a funded test key. Test recipes are in `tests/test_anvil_fork.py` (unimplemented stub — community contributions welcome).
+
+## Status & affiliation
+
+**Hypnex is not affiliated with the Morpheus AI Foundation.** The contracts you sign into are Morpheus's; this is the unofficial Python toolkit for them. Audit your own transactions; the Code4rena audit ([report](https://code4rena.com/reports/2025-08-morpheus)) covers the contracts, not this client.
+
+## License
+
+MIT

hypnex_staking-0.1.0/README.md

@@ -0,0 +1,118 @@
+# hypnex-staking (Python)
+
+On-chain helpers for the **Morpheus AI capital pool** on Ethereum mainnet. Wraps `DepositPool.stake()` and `claimReferrerTier()` so a Python developer can stake stETH/USDC/USDT/wBTC and capture **MRC 73 unlocked-MOR referral rewards**.
+
+```bash
+pip install hypnex-staking
+```
+
+## Why this exists
+
+Morpheus's `app.mor.org` UI requires AWS Cognito email signup. The capital pool's on-chain interface is wallet-native and supports referrer attribution, but no Python tooling exists for it. This package fills that gap.
+
+The single most under-marketed mechanic: **referral MOR is unlocked, while own-stake MOR is delayed 90 days** (MRC 73 vs MRC 46). Refer once, earn liquid MOR for as long as the referee stays staked.
+
+## Quickstart
+
+### Read-only (no key needed)
+
+```python
+from hypnex_staking import Staker
+
+s = Staker()  # public RPC, no signer
+
+# Inspect the live tier table
+for tier in s.get_referrer_tiers("USDC"):
+    print(tier)
+
+# Look up an existing position
+print(s.get_position("0xSomeAddress...", "USDC"))
+
+# Look up someone's referrer data
+print(s.get_referrer_data("0xReferrer...", "USDC"))
+```
+
+### With a signer (moves real funds)
+
+```python
+import os
+from hypnex_staking import Staker
+
+s = Staker(
+    rpc_url=os.environ["ETH_RPC_URL"],
+    private_key=os.environ["PRIVATE_KEY"],
+    default_referrer="0xYourHypnexLabsAddress",  # or set HYPNEX_REFERRER env
+)
+
+# Always dry-run first — returns calldata, doesn't broadcast
+print(s.stake("USDC", amount=1000, claim_lock_end=0, dry_run=True))
+
+# When ready, drop dry_run for the real tx
+tx = s.stake("USDC", amount=1000, claim_lock_end=0)
+print("submitted:", tx)
+```
+
+### Claim accumulated MRC 73 unlocked-MOR
+
+```python
+# Per MRC 73, this MOR has no 90-day lockup — claimable immediately.
+tx = s.claim_referrer_rewards("USDC")
+```
+
+## Verified contracts (Ethereum mainnet)
+
+| Contract | Address |
+|---|---|
+| USDC DepositPool | `0x6cCE082851Add4c535352f596662521B4De4750E` |
+| USDT DepositPool | `0x3B51989212BEdaB926794D6bf8e9E991218cf116` |
+| wBTC DepositPool | `0xdE283F8309Fd1AA46c95d299f6B8310716277A42` |
+| wETH DepositPool | `0x9380d72aBbD6e0Cc45095A2Ef8c2CA87d77Cb384` |
+| DistributorV2 | `0xDf1AC1AC255d91F5f4B1E3B4Aef57c5350F64C7A` |
+| ChainLinkDataConsumer | `0xd182263d06FDC463c96190005D6359CC3d3Bbc5e` |
+
+Sourced from `MorpheusAIs/SmartContracts` v7 deploy script — verified against the on-chain bytecode by `tests/test_read_only.py`.
+
+## Public API
+
+```
+Staker(w3=..., rpc_url=..., account=..., private_key=..., default_referrer=...)
+
+# read (no signer)
+.get_pool_address(asset) -> str
+.get_token_address(asset) -> str
+.get_decimals(asset) -> int
+.get_position(address, asset) -> Position
+.get_referrer_data(referrer, asset) -> ReferrerData
+.get_referrer_tiers(asset) -> list[ReferrerTier]
+.quote_tier(asset, virtual_amount_staked) -> ReferrerTier | None
+
+# write (signer required)
+.approve(asset, amount, dry_run=False) -> str (tx hash)
+.stake(asset, amount, claim_lock_end=0, referrer=None, auto_approve=True, dry_run=False) -> str
+.claim_referrer_rewards(asset, receiver=None, layerzero_fee_wei=0, dry_run=False) -> str
+```
+
+`asset` is one of `"USDC" | "USDT" | "WBTC" | "WETH"`.
+
+## Environment variables
+
+- `ETH_RPC_URL` — Ethereum mainnet RPC (free public default works for reads)
+- `PRIVATE_KEY` — for write methods only
+- `HYPNEX_REFERRER` — default referrer address (override per-call with `referrer=`)
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest                  # read-only mainnet smoke tests, no key needed
+```
+
+For write-method tests, run a local Anvil fork (`anvil --fork-url $ETH_RPC_URL`) and set `ETH_RPC_URL=http://localhost:8545` plus a funded test key. Test recipes are in `tests/test_anvil_fork.py` (unimplemented stub — community contributions welcome).
+
+## Status & affiliation
+
+**Hypnex is not affiliated with the Morpheus AI Foundation.** The contracts you sign into are Morpheus's; this is the unofficial Python toolkit for them. Audit your own transactions; the Code4rena audit ([report](https://code4rena.com/reports/2025-08-morpheus)) covers the contracts, not this client.
+
+## License
+
+MIT

hypnex_staking-0.1.0/examples/01_check_position.py

@@ -0,0 +1,30 @@
+"""Read your stake position from the Morpheus capital pool.
+
+Read-only — no key required.
+
+Run:  python examples/01_check_position.py 0xYourAddress... USDC
+"""
+
+import sys
+
+from hypnex_staking import Staker
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("usage: python 01_check_position.py <address> <USDC|USDT|WBTC|WETH>")
+        return 2
+    address, asset = sys.argv[1], sys.argv[2]
+    s = Staker()
+    p = s.get_position(address, asset)
+    decimals = s.get_decimals(asset)
+    print(f"Position for {address} in {asset.upper()} pool:")
+    print(f"  deposited        : {p.deposited / 10**decimals:,.6f} {asset.upper()}")
+    print(f"  pending rewards  : {p.pending_rewards / 1e18:,.6f} MOR")
+    print(f"  claim_lock_end   : {p.claim_lock_end} (unix)")
+    print(f"  referrer         : {p.referrer}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hypnex_staking-0.1.0/examples/02_get_referrer_data.py

@@ -0,0 +1,30 @@
+"""Read a referrer's data: amount staked under them, virtual amount, pending unlocked MOR.
+
+Read-only.
+
+Run:  python examples/02_get_referrer_data.py 0xReferrerAddress... USDC
+"""
+
+import sys
+
+from hypnex_staking import Staker
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print("usage: python 02_get_referrer_data.py <referrer> <USDC|USDT|WBTC|WETH>")
+        return 2
+    referrer, asset = sys.argv[1], sys.argv[2]
+    s = Staker()
+    d = s.get_referrer_data(referrer, asset)
+    decimals = s.get_decimals(asset)
+    print(f"Referrer data for {referrer} in {asset.upper()} pool:")
+    print(f"  amount staked under referrer  : {d.amount_staked / 10**decimals:,.6f} {asset.upper()}")
+    print(f"  virtual amount (after tier)   : {d.virtual_amount_staked / 10**decimals:,.6f}")
+    print(f"  pending unlocked MOR rewards  : {d.pending_rewards / 1e18:,.6f} MOR  (MRC 73 — claim anytime)")
+    print(f"  last claim                    : {d.last_claim} (unix)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hypnex_staking-0.1.0/examples/03_quote_tier.py

@@ -0,0 +1,37 @@
+"""Read the live referrer-tier table for each pool and quote which tier a given
+virtual stake amount falls in.
+
+Read-only.
+
+Run:  python examples/03_quote_tier.py
+"""
+
+from hypnex_staking import Staker
+
+
+def main() -> None:
+    s = Staker()
+
+    for asset in ("USDC", "USDT", "WBTC", "WETH"):
+        decimals = s.get_decimals(asset)
+        print(f"\n{asset} pool — referrer tiers:")
+        tiers = s.get_referrer_tiers(asset)
+        if not tiers:
+            print("  (no tiers configured on-chain — fall through to base 1% referee bonus)")
+            continue
+        for i, t in enumerate(tiers):
+            # multiplier is PRECISION-scaled (1e25 == 1.0×); convert to bonus %
+            multiplier_x = t.multiplier / 1e25
+            bonus_pct = (multiplier_x - 1.0) * 100
+            print(
+                f"  tier {i}: ≥ {t.amount_threshold / 10**decimals:>12,.4f} {asset} "
+                f"→ {multiplier_x:.4f}× ({bonus_pct:+.1f}%)"
+            )
+
+    print("\nNote: tier thresholds are denominated in the *virtual amount* — i.e. the\n"
+          "amount-staked × the referee's claim-lock-time multiplier. Long locks count\n"
+          "for more virtual stake, which can push a referrer up a tier.")
+
+
+if __name__ == "__main__":
+    main()

hypnex_staking-0.1.0/examples/04_stake.py

@@ -0,0 +1,67 @@
+"""WRITES A REAL TRANSACTION on Ethereum mainnet — moves real funds.
+
+Stake `amount` of `asset` into the Morpheus DepositPool with Hypnex Labs as
+the on-chain referrer. The default-referrer override happens via the
+HYPNEX_REFERRER env var or the Staker(default_referrer=...) constructor arg.
+
+Always run with --dry-run first. Test against Anvil fork before live.
+
+Run:
+    ETH_RPC_URL=https://... \\
+    PRIVATE_KEY=0x... \\
+    python examples/04_stake.py USDC 100 --dry-run
+
+To broadcast for real, drop the --dry-run flag.
+"""
+
+import argparse
+import os
+
+from hypnex_staking import Staker
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("asset", choices=["USDC", "USDT", "WBTC", "WETH"])
+    p.add_argument("amount", type=float)
+    p.add_argument("--claim-lock-end", type=int, default=0,
+                   help="Unix timestamp for voluntary additional claim lock; 0 = no extra lock")
+    p.add_argument("--referrer", type=str, default=None,
+                   help="Override default referrer (HYPNEX_REFERRER env / Staker default)")
+    p.add_argument("--dry-run", action="store_true",
+                   help="Build but do NOT broadcast — print calldata only")
+    args = p.parse_args()
+
+    rpc = os.environ.get("ETH_RPC_URL")
+    pk = os.environ.get("PRIVATE_KEY")
+    if not rpc or not pk:
+        print("error: set ETH_RPC_URL and PRIVATE_KEY")
+        return 2
+
+    s = Staker(rpc_url=rpc, private_key=pk)
+
+    print(f"  asset            : {args.asset}")
+    print(f"  amount           : {args.amount}")
+    print(f"  claim_lock_end   : {args.claim_lock_end}")
+    print(f"  referrer         : {args.referrer or s.default_referrer}")
+    print(f"  signer           : {s.account.address}")
+    print(f"  pool             : {s.get_pool_address(args.asset)}")
+    print(f"  dry_run          : {args.dry_run}")
+    print()
+
+    out = s.stake(
+        asset=args.asset,
+        amount=args.amount,
+        claim_lock_end=args.claim_lock_end,
+        referrer=args.referrer,
+        dry_run=args.dry_run,
+    )
+    if args.dry_run:
+        print(f"  encoded calldata : {out}")
+    else:
+        print(f"  tx hash          : {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hypnex_staking-0.1.0/examples/05_claim_referrer_rewards.py

@@ -0,0 +1,43 @@
+"""WRITES A REAL TRANSACTION — claims your accumulated MRC 73 unlocked-MOR rewards.
+
+Per MRC 73, referrer MOR is unlocked the moment it accrues — no 90-day delay
+that capital contributors face under MRC 46. This is the lowest-friction MOR
+yield path on the network.
+
+Run:
+    ETH_RPC_URL=... PRIVATE_KEY=... \\
+    python examples/05_claim_referrer_rewards.py USDC --dry-run
+"""
+
+import argparse
+import os
+
+from hypnex_staking import Staker
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("asset", choices=["USDC", "USDT", "WBTC", "WETH"])
+    p.add_argument("--receiver", type=str, default=None,
+                   help="Address to receive the MOR (defaults to signer)")
+    p.add_argument("--lz-fee-wei", type=int, default=0,
+                   help="LayerZero messaging fee if cross-chain forwarding (default 0)")
+    p.add_argument("--dry-run", action="store_true")
+    args = p.parse_args()
+
+    rpc = os.environ["ETH_RPC_URL"]
+    pk = os.environ["PRIVATE_KEY"]
+    s = Staker(rpc_url=rpc, private_key=pk)
+
+    out = s.claim_referrer_rewards(
+        asset=args.asset,
+        receiver=args.receiver,
+        layerzero_fee_wei=args.lz_fee_wei,
+        dry_run=args.dry_run,
+    )
+    print(f"{'calldata' if args.dry_run else 'tx hash'}: {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())