axis-synome 0.1.dev184__py3-none-any.whl

axis_synome/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.dev184'
+__version_tuple__ = version_tuple = (0, 1, 'dev184')
+
+__commit_id__ = commit_id = None

axis_synome/spec/asc/README.md

@@ -0,0 +1,419 @@
+# Actively Stabilizing Capital (ASC) Specification
+
+This module is the executable specification for Sky Protocol's **Actively Stabilizing Capital** framework. It encodes the rules from the Sky Atlas into typed Python so that constraints can be evaluated, tested, and audited against live position data.
+
+---
+
+## Background
+
+Sky Protocol issues **USDS**, a stablecoin pegged to one US dollar. The peg is only as strong as the liquid capital standing behind it. The Atlas defines **Actively Stabilizing Capital (ASC)** as the safety net every Prime Agent must maintain to absorb redemption pressure and defend the peg.
+
+This specification answers: *does a given Prime, given its current positions, satisfy all ASC-related obligations?*
+
+---
+
+## Module Layout
+
+```
+entities/       : data types and constants (the inputs)
+formulas/       : pure functions that compute values from entities (the logic)
+```
+
+All formulas follow one rule: **they accept raw entity inputs / placeholders and compute everything internally**. No formula accepts a precomputed intermediate value as an argument.
+
+---
+
+## Entities
+
+### `Position` (`entities/types.py`)
+
+It is one of the fundamental units. It represents a single holding of a token in a protocol on a network.
+
+| Field | Type | Description |
+|---|---|---|
+| `token` | `str` | Token symbol, e.g. `"USDC"` |
+| `protocol` | `Protocol` | Protocol name, e.g. `Protocol.LITE_PSM`, `Protocol.CURVE` |
+| `network` | `Network` | Chain, e.g. `Network.ETHEREUM_MAINNET`, `Network.BASE` |
+| `value_usd` | `float` | USD value of this position |
+| `owner` | `str \| None` | Prime name this position belongs to |
+| `pool_paired_with_usds` | `bool \| None` | For pool positions: whether the pair token is USDS |
+| `fee_tier` | `float \| None` | For G-UNI positions: fee tier (e.g. `0.0001`) |
+
+Every formula filters positions by `p.owner == prime.name` so each Prime is evaluated against only its own capital.
+
+---
+
+### `PrimeAgent` (`entities/primes.py`)
+
+It represents one Sky Star Agent & holds both identity data and governance parameters.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | `str` | — | Prime identifier, e.g. `"Spark"` |
+| `output_stablecoins` | `set[str]` | `{}` | Stablecoins this Prime issues (used for DAB) |
+| `psm_protocols` | `set[str]` | `{}` | Prime's own PSM protocol names (used for DAB) |
+| `alm_proxy` | `str \| None` | `None` | ALM proxy protocol name; if set, positions there count as Latent ASC |
+| `allocation_buffer_protocol` | `str \| None` | `None` | Allocation buffer protocol name (used for DAB) |
+| `networks` | `set[Network]` | `{}` | Networks this Prime operates on |
+| `max_pct_latent_asc` | `float \| None` | `None` | Max fraction of total ASC that may be Latent ASC. Must be ≤ 0.25. Must be set before calling `ratio_latent_asc`. |
+| `asc_exempt` | `bool` | `False` | If `True`, this Prime is exempt from ASC calculations. Exempt primes are excluded from `EligiblePrimeAgentASC` (used by `asc()`). |
+| `min_pct_asc_of_collateral` | `float` | `0.05` | Minimum fraction of the Collateral Portfolio that must be held as ASC. Fixed at 5% by protocol rule. |
+
+**Validation:** `max_pct_latent_asc` must be set to a value ≤ 0.25 before calling `ratio_latent_asc`. It is not enforced at construction time.
+
+#### Registered Primes
+
+| Prime | `asc_exempt` | Notes |
+|---|---|---|
+| Spark | `False` | Largest Sky Direct exposure |
+| Grove | `False` | Institutional tokenized credit |
+| Keel | **`True`** | Operates on Solana; exempt from minimum ASC |
+| Skybase | `False` | — |
+| Pattern | `False` | Onboarding 2026 |
+| Launch Agent 6 | `False` | — |
+| Launch Agent 7 | `False` | — |
+
+### `EligiblePrimeAgentASC` (`entities/primes.py`)
+
+Enum of non-exempt `PrimeAgent` instances eligible for ASC calculations. Excludes ASC-exempt primes (e.g., Keel). Each member's `.value` is the underlying `PrimeAgent` instance.
+
+Members: `SPARK`, `GROVE`, `SKYBASE`, `PATTERN`, `LAUNCH_AGENT_6`, `LAUNCH_AGENT_7`.
+
+---
+
+### Constants (`entities/tokens.py`, `entities/networks.py`, `entities/protocol_sets.py`)
+
+| Constant | Values |
+|---|---|
+| `CASH_STABLECOINS` | `USDC`, `USDS`, `DAI`, `USDT` |
+| `L2_NETWORKS` | `Base`, `Arbitrum`, `Optimism`, `Unichain` |
+| `L1_PSM_PROTOCOLS` | `LitePSM` |
+| `L2_PSM_PROTOCOLS` | `PSM3` |
+| `LENDING_PROTOCOLS` | SparkLend, Aave, Morpho (and variants), Kamino, Maple |
+| `POOL_PROTOCOLS` | `Curve`, `Uniswap` |
+| `GUNI_PROTOCOLS` | `GUNI` |
+| `GUNI_RESTING_FEE_TIERS` | `0.0001` (0.01%), `0.0005` (0.05%) |
+
+---
+
+## Formulas
+
+Each ASC related formula is a pure function `(prime, positions) -> float`. Slack formulas return a value that must be `>= 0` for the constraint to be satisfied; a negative result means a breach.
+
+---
+
+### `resting_asc(prime, positions)` → `float`
+
+**File:** `formulas/resting_asc.py`
+
+Capital that is immediately liquid and already defending the peg. These are positions that can absorb USDS redemptions right now, without any conversion step.
+
+**Counts positions where `p.owner == prime.name` AND:**
+
+| Condition | What it captures |
+|---|---|
+| `protocol in L1_PSM_PROTOCOLS` and `token == "USDC"` | USDC in LitePSM (Ethereum) |
+| `protocol in L2_PSM_PROTOCOLS` and `token == "USDC"` and `network in L2_NETWORKS` | USDC in PSM3 on Base, Arbitrum, Unichain, Optimism |
+| `protocol in POOL_PROTOCOLS` and `token in CASH_STABLECOINS` and `pool_paired_with_usds == True` | Cash stablecoins in Curve/Uniswap pools paired with USDS |
+| `protocol in GUNI_PROTOCOLS` and `token == "USDC"` and `fee_tier in GUNI_RESTING_FEE_TIERS` | USDC in G-UNI at 0.01% or 0.05% fee tiers |
+
+---
+
+### `latent_asc(prime, positions)` → `float`
+
+**File:** `formulas/latent_asc.py`
+
+Capital that could be mobilised within 15 minutes but is not currently defending the peg. It is earning yield while standing ready. The conversion to Resting ASC must be fully automated.
+
+**Counts positions where `p.owner == prime.name` AND `token in CASH_STABLECOINS` AND:**
+
+| Condition | What it captures |
+|---|---|
+| `protocol in POOL_PROTOCOLS` and `pool_paired_with_usds == False` | Cash stablecoins in Curve/Uniswap pools NOT paired with USDS |
+| `protocol in LENDING_PROTOCOLS` | Cash stablecoins deposited in SparkLend, Aave, Morpho, etc. |
+| `protocol == prime.alm_proxy` (when set) | Cash stablecoins in the Prime's ALM proxy |
+
+---
+
+### `asc(prime: EligiblePrimeAgentASC, positions)` → `float`
+
+**File:** `formulas/asc.py`
+
+Total Actively Stabilizing Capital. The sum of all stabilizing capital, both immediately liquid and held in reserve.
+
+```
+ASC = RestingASC + LatentASC
+```
+
+`asc()` accepts only members of `EligiblePrimeAgentASC`, which by design excludes exempt Primes. As a result, exempt Primes (e.g., Keel) cannot be evaluated with `asc()`.
+
+---
+
+### Constraints
+
+The following formulas are **slack functions**: they return a number that must be `>= 0`. A negative value signals a breach of the corresponding Atlas rule.
+
+---
+
+#### `ratio_latent_asc(prime, positions)` → `float`
+
+**File:** `formulas/ratio_latent_asc.py`
+
+Enforces the rule: *Latent ASC may not exceed `max_pct_latent_asc` of total ASC.*
+
+```
+slack = ASC × max_pct_latent_asc − LatentASC
+```
+
+- Positive (or zero): Latent ASC is within the permitted fraction.
+- Negative: Latent ASC is too high — the Prime must convert reserves to Resting positions.
+
+**Parameter on Prime:** `max_pct_latent_asc` — must be set (not `None`) and must be ≤ 0.25. The Atlas cap is 25%; individual Primes may be held to a stricter limit.
+
+**Raises `ValueError`** if `max_pct_latent_asc` has not been configured on the Prime.
+
+---
+
+#### `dab_actual(prime, positions)` → `float`
+
+**File:** `formulas/dab.py`
+
+The Prime's actual Demand Absorption Buffer: prime-issued stablecoins held in the Prime's own PSM protocols or allocation buffer, available to be sold at no more than $1.001 per USDS to absorb upward peg pressure.
+
+**Counts positions where:**
+- `token in prime.output_stablecoins` (the Prime's own issued stablecoins)
+- AND (`protocol in prime.psm_protocols` OR `protocol == prime.allocation_buffer_protocol`)
+
+---
+
+#### `dab_required(prime, positions)` → `float`
+
+**File:** `formulas/dab.py`
+
+The minimum DAB the Prime must hold, computed as a fixed fraction of its total ASC.
+
+```
+DABRequired = ASC × DAB_REQUIRED_PCT
+```
+
+**Global constant:** `DAB_REQUIRED_PCT = 0.25` (25%), fixed by Atlas rule. Every Prime must maintain a DAB equal to 25% of their required ASC.
+
+---
+
+#### `dab_satisfied(prime, positions)` → `float`
+
+**File:** `formulas/dab.py`
+
+Slack for the DAB constraint. Must be `>= 0`.
+
+```
+slack = DABActual − DABRequired
+```
+
+---
+
+#### `asc_collateral_ratio(prime, positions)` → `float`
+
+**File:** `formulas/asc_collateral_ratio.py`
+
+Enforces the rule: *ASC must be at least `min_pct_asc_of_collateral` of the Prime's total Collateral Portfolio.*
+
+```
+CollateralPortfolio = sum of value_usd for all positions owned by the Prime
+slack = ASC − CollateralPortfolio × min_pct_asc_of_collateral
+```
+
+- Positive (or zero): ASC meets the minimum threshold.
+- Negative: The Prime's ASC is too small relative to its total portfolio.
+
+**Parameter on Prime:** `min_pct_asc_of_collateral` — defaults to `0.05` (5%), fixed by Atlas rule.
+
+---
+
+### `asc_incentive(prime, positions, base_rate, treasury_bill_rate)` → `float`
+
+**File:** `formulas/asc_incentive.py`
+
+The payment a Prime receives for maintaining ASC. If the base rate exceeds the T-bill rate, maintaining ASC is profitable. If not, it is a cost the Prime bears for operating in the Sky ecosystem.
+
+```
+ASCIncentive = ASC × (base_rate − treasury_bill_rate)
+```
+
+`base_rate` and `treasury_bill_rate` are external market/governance inputs passed directly as parameters — they are not properties of a Prime.
+
+---
+
+## How the Constraints Fit Together
+
+For every member of `EligiblePrimeAgentASC`, all of the following must hold simultaneously:
+
+| Constraint | Slack formula | Must be |
+|---|---|---|
+| Latent ASC ≤ `max_pct_latent_asc` of total ASC | `ratio_latent_asc` | ≥ 0 |
+| DAB actual ≥ 25% of ASC | `dab_satisfied` | ≥ 0 |
+| ASC ≥ 5% of Collateral Portfolio | `asc_collateral_ratio` | ≥ 0 |
+
+**Keel is automatically skipped**: it is not a member of `EligiblePrimeAgentASC`, so `asc()` is never called for Keel. Iterate over `EligiblePrimeAgentASC` when computing ASC-dependent constraints.
+
+---
+
+## Slack Formulas
+
+A slack formula measures **how far above (or below) a constraint threshold** a Prime currently sits.
+
+The pattern is always:
+
+```
+slack = actual − required
+```
+
+| Slack value | Meaning |
+|---|---|
+| Positive | Compliant with headroom — the Prime exceeds the requirement by that amount |
+| Zero | Exactly at the limit — compliant, but no buffer |
+| Negative | Breaching the constraint — the shortfall is the absolute value |
+
+For example, `dab_satisfied` returns `DABActual − DABRequired`. A result of `−50,000` means the Prime is $50,000 short of its required DAB. A result of `+200,000` means it has $200,000 of buffer above the minimum.
+
+The advantage over a simple boolean pass/fail check is that you can see **how close to the edge** a Prime is, not just whether it passed or failed. This makes slack values directly useful for monitoring, graduated alerting (e.g. warn when slack < 10%), and audit reporting.
+
+---
+
+## Design Principles
+
+1. **No precomputed inputs.** Every formula accepts raw entities (`PrimeAgent`, `list[Position]`) and computes all intermediates internally. This makes formulas independently testable and prevents silent staleness bugs.
+
+2. **Governance parameters live on the entity.** Values that can change per-prime (e.g. `max_pct_latent_asc`, `min_pct_asc_of_collateral`) are fields on `PrimeAgent`, not magic numbers buried in formulas. Protocol-wide constants (e.g. `DAB_REQUIRED_PCT`) are module-level constants in the relevant formula file. To change a limit, update the entity or constant — the formula picks it up automatically.
+
+3. **Optional parameters signal missing configuration.** Parameters like `max_pct_latent_asc` that have no universal default are `None` until explicitly set. Formulas raise a clear `ValueError` rather than silently producing wrong results.
+
+4. **Slack semantics are consistent.** All constraint functions return a value where `>= 0` means compliant and `< 0` means breached, by the same amount. This makes threshold monitoring uniform across all constraints.
+
+---
+
+## Connecting External Data
+
+### Overview
+
+Data you fetch from an on-chain indexer, a REST API, or a database arrives as raw records — dictionaries, CSV rows, or ORM objects. Before passing data to any formula, it must be converted into `Position` objects. This conversion is the **adapter step**.
+
+The order matters:
+
+```
+1. Fetch     : pull raw records from your data source (could be multiple)
+2. Adapt     : map raw records to Position objects
+3. Evaluate  : pass positions to the formula
+```
+
+### Step 1: Fetch
+
+Pull position records from your source. The exact method depends on what you have (could be an API client, a database query, or a file reader). The result is anticipated be a list of dicts (or any iterable of mappings). This needs to be clarified.
+
+```python
+# From a REST API
+raw_records = api_client.get("/positions?prime=Spark").json()
+
+# From a database
+raw_records = db.execute(
+    "SELECT token, protocol, network, usd_value FROM positions WHERE prime = ?", ("Spark",)
+).fetchall()
+
+# From a CSV file (via the standard library)
+import csv
+
+with open("positions.csv") as f:
+    raw_records = list(csv.DictReader(f))
+```
+
+### Step 2: Adapt
+
+Convert each raw record into a `Position`. The `owner` is always passed separately, it is governance metadata that your data source does not carry.
+
+```python
+from axis_synome.spec.asc.entities.types import Position
+
+
+def adapt(records: list[dict], owner: str) -> list[Position]:
+    return [
+        Position(
+            token=r["token"],
+            protocol=r["protocol"],
+            network=r["network"],
+            value_usd=float(r["value_usd"]),
+            owner=owner,  # For ex. the prime's name
+            pool_paired_with_usds=r.get("pool_paired_with_usds"),
+            fee_tier=r.get("fee_tier"),
+        )
+        for r in records
+    ]
+```
+
+`pool_paired_with_usds` and `fee_tier` are optional so one can use `.get()` so that records that do not carry them default to `None`.
+
+### Step 3: Evaluate
+
+Pass the adapted positions directly to any formula.
+
+```python
+from axis_synome.spec.asc.entities.primes import SPARK, EligiblePrimeAgentASC
+from axis_synome.spec.asc.formulas.asc import asc
+from axis_synome.spec.asc.formulas.dab import dab_satisfied
+from axis_synome.spec.asc.formulas.asc_collateral_ratio import asc_collateral_ratio
+
+positions = adapt(raw_records, owner="Spark")
+
+# Or make a loop for all Primes
+print(asc(EligiblePrimeAgentASC.SPARK, positions))
+print(dab_satisfied(SPARK, positions))
+print(asc_collateral_ratio(SPARK, positions))
+```
+
+---
+
+### When the field names do not match
+
+`Position` expects specific field names. If your data source uses different names, the call `Position(**row)` will raise a `TypeError`. Fix this once in the adapter, not in the formula.
+
+Example: your API returns `usd_value` instead of `value_usd`, and `asset` instead of `token`.
+
+```python
+# Your raw record
+{"asset": "USDC", "protocol": "LitePSM", "network": "Ethereum", "usd_value": 1_000_000.0}
+```
+
+Adapter that renames fields before construction:
+
+```python
+def adapt(records: list[dict], owner: str) -> list[Position]:
+    return [
+        Position(
+            token=r["asset"],  # renamed: asset -> token
+            protocol=r["protocol"],
+            network=r["network"],
+            value_usd=float(r["usd_value"]),  # renamed: usd_value -> value_usd
+            owner=owner,
+            pool_paired_with_usds=r.get("pool_paired_with_usds"),
+            fee_tier=r.get("fee_tier"),
+        )
+        for r in records
+    ]
+```
+
+PS: **your data source dictates whatever naming it chooses; the adapter is where you reconcile that with `Position`'s field names**. Formulas and tests are not aware of the user source's naming for now.
+
+---
+
+### Required vs Optional Fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `token` | Yes | Token symbol, e.g. `"USDC"` |
+| `protocol` | Yes | Protocol name, e.g. `"LitePSM"` |
+| `network` | Yes | Chain name, e.g. `"Ethereum"`, `"Base"` |
+| `value_usd` | Yes | USD value as a float |
+| `owner` | Passed separately | The prime's name; not expected to be in raw records |
+| `pool_paired_with_usds` | No | Needed for pool positions; `None` otherwise |
+| `fee_tier` | No | Needed for G-UNI positions; `None` otherwise |
+
+If a required field is missing from a record, the adapter will raise a `KeyError`. That is intentional — it means your data source is incomplete and you should fix the fetch query, not add a fallback.

axis_synome/spec/asc/entities/__init__.py

@@ -0,0 +1 @@
+

axis_synome/spec/asc/entities/assets.py

@@ -0,0 +1,17 @@
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec_support.evm_address import EvmAddress
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class Asset:
+    token: Token
+    network: Network
+    protocol: Protocol
+    address: EvmAddress
+    underlying_asset: Token
+    underlying_asset_address: EvmAddress
+    underlying_asset_source: str
+    source: str | None = None