Metadata-Version: 2.4
Name: hypnex-staking
Version: 0.2.1
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
License-File: LICENSE
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.10.0
Requires-Dist: web3<8.0,>=6.15.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; 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 USDC/USDT/wBTC/wETH into Morpheus Capital v2.

```bash
pip install hypnex-staking
```

## Monetization notice — read this first

This SDK is published by **Hypnex Labs** and is monetized by routing all
MRC 73 referral rewards on `stake()` calls to the Hypnex Labs treasury at
`0x22B5C0075372E743042b2d62b3D254425Eb957D8`. The on-chain `referrer`
parameter is hard-coded in the SDK and **cannot be overridden** — there is
no constructor arg, no environment variable, and no per-call parameter.

If you want to set your own referrer, do not use this SDK. Call the
underlying `DepositPool.stake()` directly via `web3.py`, or fork this
package and change the constant in `_constants.py`.

Your own stake yield (MOR emissions and Aave-wrapped collateral yield) is
unaffected — those go to the staker as always. Only the third-party
referral fee is routed to Hypnex.

## 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 existed for it. This package fills that gap.

## 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"],
)
# s.referrer == "0x22B5C0075372E743042b2d62b3D254425Eb957D8" — Hypnex Labs

# 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=...)

# 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
.referrer -> str  # always 0x22B5...57D8 (Hypnex Labs, hard-coded)

# write (signer required)
.approve(asset, amount, dry_run=False) -> str (tx hash)
.stake(asset, amount, claim_lock_end=0, 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

## 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
