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
