axis-synome 0.1.0.dev35__tar.gz → 0.1.0.dev36__tar.gz

{axis_synome-0.1.0.dev35 → axis_synome-0.1.0.dev36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev35
+Version: 0.1.0.dev36
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev35 → axis_synome-0.1.0.dev36}/src/axis_synome/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0.dev35'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev35')
+__version__ = version = '0.1.0.dev36'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev36')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev36/src/axis_synome/spec/entities/__init__.py

@@ -0,0 +1,5 @@
+"""Shared domain entities for the Sky Atlas specification.
+
+Entity types defined here are imported by formulas across multiple
+specification areas (e.g. risk_capital, asc).
+"""

axis_synome-0.1.0.dev36/src/axis_synome/spec/entities/protocol_risk.py

@@ -0,0 +1,29 @@
+"""Backdoor types and protocol risk profiles.
+
+Defines the protocol-level risk profile used by Smart Contract and
+Administrative RRC models, including backdoor classification types
+and their associated risk weights.
+"""
+
+from enum import Enum
+
+
+class BackdoorType(Enum):
+    """Protocol backdoor classification (A.3.2.2.1.3.1.2).
+
+    Captures the privileged-access profile of a protocol, which drives
+    the Starting Rate used in the Administrative Risk Rating (ARR):
+
+        NO_BACKDOOR      — no privileged access to the relevant contracts
+                           by any whitelisted set of users. SR = 0.
+        LIMITED_BACKDOOR — privileged users can materially modify the
+                           terms of the smart contracts (e.g. freeze
+                           transfers) but cannot make arbitrary changes
+                           or transfer user funds. SR = 50.
+        ROOT_BACKDOOR    — privileged users can make arbitrary changes,
+                           including transferring user funds. SR = 100.
+    """
+
+    NO_BACKDOOR = "NoBackdoor"
+    LIMITED_BACKDOOR = "LimitedBackdoor"
+    ROOT_BACKDOOR = "RootBackdoor"

axis_synome-0.1.0.dev36/src/axis_synome/spec/risk_capital/administrative_rrc/__init__.py

@@ -0,0 +1 @@
+"""Instance Administrative Required Risk Capital."""

axis_synome-0.1.0.dev36/src/axis_synome/spec/risk_capital/administrative_rrc/administrative_risk.py

@@ -0,0 +1,238 @@
+"""ARR formulas and related parameters.
+
+Administrative Risk is the risk of loss due to abuse of privileged
+access to the smart contracts that a Prime Agent invests in — e.g. a
+multisig or other actor that can modify protocol terms or move funds
+outside of a governance process.
+
+The Instance Administrative RRC is computed in two steps:
+
+    1. Administrative Risk Rating (ARR) — A.3.2.2.1.3.1
+       A protocol-level rating on [0, 100], composed from:
+         - Starting Rate (SR): backdoor-type driven base (0, 50, 100)
+         - Delay Factor (DF): mitigation from a security delay, [0, 1]
+         - Lindy Adjustment Factor (LAF): shared helper (A.3.2.2.1.2.2.4)
+       ARR = min(CAP, SR * DF * LAF), with CAP a temporary cap.
+
+    2. Instance Administrative RRC — A.3.2.2.1.3.2
+       The ARR is converted into a Capital Requirement Ratio using the
+       same piecewise methodology as Smart Contract RRC
+       (A.3.2.2.1.2.3), then multiplied by the Prime's exposure.  The
+       rating-to-CRR mapping is intentionally shared with Smart
+       Contract RRC and therefore delegated to that module; this file
+       defines only the Administrative-specific rating inputs and the
+       per-protocol exceptions (A.3.2.2.1.3.3) that override the rating
+       computation.
+"""
+
+from typing import Final
+
+from axis_synome.spec.entities.protocol_risk import BackdoorType
+from axis_synome.spec.risk_capital.lindy_factor import lindy_adjustment_factor
+
+# ── Administrative Risk Rating Cap (A.3.2.2.1.3.1.1) ──────────────
+
+ADMINISTRATIVE_RISK_RATING_CAP: Final[float] = 30.0
+"""Temporary cap on the Administrative Risk Rating.
+
+:source_uuid: 7e359ea6-e846-4977-b3db-87fc1db64c0f
+"""
+
+# ── Starting Rates by backdoor type (A.3.2.2.1.3.1.2.*) ───────────
+
+STARTING_RATE_NO_BACKDOOR: Final[float] = 0.0
+"""Starting Rate for a protocol with no backdoor access.
+
+:source_uuid: 0d40ea83-8eef-4bea-b1ca-5700fb4536bc
+"""
+
+STARTING_RATE_LIMITED_BACKDOOR: Final[float] = 50.0
+"""Starting Rate for a protocol with limited backdoor access.
+
+:source_uuid: ef31a379-c7ea-43c6-9a68-0f6083fcfeaf
+"""
+
+STARTING_RATE_ROOT_BACKDOOR: Final[float] = 100.0
+"""Starting Rate for a protocol with root backdoor access.
+
+:source_uuid: 7d203683-a16c-479c-8425-2fed3b4c2375
+"""
+
+# ── Delay Factor parameter (A.3.2.2.1.3.1.3) ─────────────────────
+
+MAX_SECURITY_DELAY_HOURS: Final[float] = 48.0
+"""Security delay (in hours) at or above which the Delay Factor is zero; it decays linearly from 1.0 at 0h.
+
+:source_uuid: 52511026-55f4-4848-95a2-53db048d906c
+"""
+
+# ── Per-protocol exceptions (A.3.2.2.1.3.3) ───────────────────────
+#
+# Exceptions land at two different layers:
+#   - Rating-layer (A.3.2.2.1.3.3.5 Fluid): overrides the ARR itself,
+#     which then flows through the standard rating-to-CRR mapping.
+#   - CRR-layer (A.3.2.2.1.3.3.{1,3,4}): zero out the Administrative
+#     CRR directly, short-circuiting the rating computation.  Per the
+#     linked Smart Contract sub-docs (A.3.2.2.1.2.4.{1,3,4}) the same
+#     rule also zeroes the Smart Contract CRR; SC-side anchors will be
+#     declared alongside that module when it lands.
+#   - Exposure-layer (A.3.2.2.1.3.3.2 Legal Recourse Assets): not
+#     declared here; it is a multi-parameter exposure formula that
+#     belongs with the exposure / Smart Contract RRC work.
+
+FLUID_ADMINISTRATIVE_RISK_RATING: Final[float] = 25.0
+"""Administrative Risk Rating for Fluid (exception).
+
+:source_uuid: 6bbbfa59-7988-4d34-bd75-05402d8ac6f8
+"""
+
+BUIDL_GROUP_ADMINISTRATIVE_CRR: Final[float] = 0.0
+"""Administrative CRR for BUIDL, JTRSY, USTB, and JAAA (exception).
+
+:source_uuid: 095464ba-2301-4bb6-b342-e840bdd3c018
+"""
+
+ETHENA_ADMINISTRATIVE_CRR: Final[float] = 0.0
+"""Administrative CRR for Ethena (exception).
+
+:source_uuid: 2397551e-9704-435e-b815-0384429be224
+"""
+
+SUPERSTATE_ADMINISTRATIVE_CRR: Final[float] = 0.0
+"""Administrative CRR for Superstate (exception).
+
+:source_uuid: 92c06f19-21a3-4aea-9503-db685b3fd7f9
+"""
+
+
+# ── Starting Rate selection (A.3.2.2.1.3.1.2) ────────────────────
+
+
+def starting_rate(
+    backdoor_type: BackdoorType,
+) -> float:
+    """Select the Starting Rate for the Administrative Risk Rating (A.3.2.2.1.3.1.2).
+
+    The Starting Rate is the initial risk rating for Administrative
+    Risk before the Delay Factor and Lindy Adjustment Factor are
+    applied.  It is a piecewise function of the protocol's backdoor
+    classification:
+
+        NO_BACKDOOR      → 0
+        LIMITED_BACKDOOR → 50
+        ROOT_BACKDOOR    → 100
+
+    Args:
+        backdoor_type: The protocol's backdoor classification (see
+                       ``BackdoorType``).  A protocol's backdoor type
+                       is a governance input determined as part of
+                       onboarding the Instance.
+
+    :source_uuid: 368786cb-da80-4d48-a2e8-52d14fb6320c
+    """
+    return (
+        STARTING_RATE_NO_BACKDOOR
+        if backdoor_type == BackdoorType.NO_BACKDOOR
+        else (
+            STARTING_RATE_LIMITED_BACKDOOR
+            if backdoor_type == BackdoorType.LIMITED_BACKDOOR
+            else STARTING_RATE_ROOT_BACKDOOR
+        )
+    )
+
+
+# ── Delay Factor (A.3.2.2.1.3.1.3) ───────────────────────────────
+
+
+def delay_factor(
+    security_delay_hours: float,
+) -> float:
+    """Compute the Delay Adjustment Factor for a given security delay (A.3.2.2.1.3.1.3).
+
+    A security delay between the approval of a backdoor change and its
+    activation gives users time to raise issues or withdraw funds,
+    mitigating the risk associated with backdoor access.  The Delay
+    Factor scales the ARR accordingly:
+
+        DF = max(0, 1 - security_delay_hours / MAX_SECURITY_DELAY_HOURS)
+
+    So DF is 1 when there is no security delay, 0 at a delay of 48
+    hours or greater, and for example 0.5 at 24 hours (per the Atlas
+    illustrative example).
+
+    Args:
+        security_delay_hours: Time between approval of a backdoor
+                              change and it becoming effective, in
+                              hours (>= 0).
+
+    :source_uuid: 52511026-55f4-4848-95a2-53db048d906c
+    """
+    return max(0.0, 1.0 - security_delay_hours / MAX_SECURITY_DELAY_HOURS)
+
+
+# ── Administrative Risk Rating (A.3.2.2.1.3.1) ───────────────────
+
+
+def administrative_risk_rating(
+    starting_rate_value: float,
+    delay_factor_value: float,
+    lindy_adjustment_factor_value: float,
+) -> float:
+    """Compute the Administrative Risk Rating for a protocol (A.3.2.2.1.3.1).
+
+        ARR = min(CAP, SR * DF * LAF)
+
+    where:
+      - SR   is the Starting Rate from the backdoor type
+             (A.3.2.2.1.3.1.2), obtained via ``starting_rate``.
+      - DF   is the Delay Factor from any security delay
+             (A.3.2.2.1.3.1.3), obtained via ``delay_factor``.
+      - LAF  is the Lindy Adjustment Factor (A.3.2.2.1.3.1.4), which
+             uses the same methodology as Smart Contract RRC
+             (A.3.2.2.1.2.2.4) and is supplied by the shared Lindy
+             helper.
+      - CAP  is the Administrative Risk Rating cap (A.3.2.2.1.3.1.1),
+             a temporary governance-set ceiling on the rating.
+
+    Args:
+        starting_rate_value:           SR in [0, 100] (see ``starting_rate``).
+        delay_factor_value:            DF in [0, 1] (see ``delay_factor``).
+        lindy_adjustment_factor_value: LAF in [0, 1] from the shared
+                                       Lindy helper
+                                       (``lindy_adjustment_factor``,
+                                       A.3.2.2.1.2.2.4).
+
+    :source_uuid: a9dfd122-2862-4759-aba7-482f86428ca7
+    """
+    raw_rating: float = starting_rate_value * delay_factor_value * lindy_adjustment_factor_value
+    return min(ADMINISTRATIVE_RISK_RATING_CAP, raw_rating)
+
+
+def administrative_risk_rating_from_inputs(
+    backdoor_type: BackdoorType,
+    security_delay_hours: float,
+    age_days: float,
+    gm_tvl: float,
+) -> float:
+    """Compose the ARR directly from raw protocol-level inputs (A.3.2.2.1.3.1).
+
+    A convenience top-level formula that chains ``starting_rate``,
+    ``delay_factor``, and the shared ``lindy_adjustment_factor`` helper
+    (A.3.2.2.1.2.2.4) into ``administrative_risk_rating``.
+
+    Args:
+        backdoor_type:        Protocol backdoor classification.
+        security_delay_hours: Security delay applied to backdoor
+                              changes, in hours (>= 0).
+        age_days:             Average age of the relevant contracts,
+                              in days, used by the Lindy helper.
+        gm_tvl:               Geometric-mean daily TVL over the
+                              contract age, in USD, used by the Lindy
+                              helper.
+
+    :source_uuid: a9dfd122-2862-4759-aba7-482f86428ca7
+    """
+    sr: float = starting_rate(backdoor_type)
+    df: float = delay_factor(security_delay_hours)
+    laf: float = lindy_adjustment_factor(age_days, gm_tvl)
+    return administrative_risk_rating(sr, df, laf)

axis_synome-0.1.0.dev36/src/axis_synome/spec/risk_capital/lindy_factor.py

@@ -0,0 +1,51 @@
+import math
+from typing import Final
+
+DAYS_PER_MONTH = 365.0 / 12.0
+
+TVL_THRESHOLD_LINDY: Final[float] = 100_000_000.0
+"""TVL threshold (USD) used to scale the effective Lindy age.
+
+:source_uuid: c7939b23-39e1-4299-9beb-700857b8f90e
+"""
+
+LAF_DECAY_FACTOR_LAMBDA: Final[float] = 0.1
+"""Decay factor lambda controlling the curvature of the Lindy Adjustment Factor.
+
+:source_uuid: 7f109cc0-ee8d-48b6-8fbf-6e363004edfb
+"""
+
+LAF_MAXIMUM_AGE_MONTHS: Final[float] = 60.0
+"""Maximum effective age (in months) at which the Lindy Adjustment Factor saturates to 1.
+
+:source_uuid: 891eab12-0c47-4b87-b867-3cba6ca7db4e
+"""
+
+
+def age_effective_lindy(age_days: float, gm_tvl: float) -> float:
+    """Compute Atlas effective age from contract age and geometric-mean TVL.
+
+    Args:
+        age_days: Average age of the relevant contracts, measured in days.
+        gm_tvl: Geometric mean of daily TVL over the contract age, in USD.
+
+    :source_uuid: a8db99b2-f072-4132-9ee2-c8ebcc2b3609
+    """
+    contract_age_months = age_days / DAYS_PER_MONTH
+    scale = math.log(1.0 + gm_tvl / TVL_THRESHOLD_LINDY)
+    return contract_age_months * scale
+
+
+def lindy_adjustment_factor(age_days: float, gm_tvl: float) -> float:
+    """Compute the Atlas Lindy Adjustment Factor for smart contract risk.
+
+    Args:
+        age_days: Average age of the relevant contracts, measured in days.
+        gm_tvl: Geometric mean of daily TVL over the contract age, in USD.
+
+    :source_uuid: 227eff62-f2aa-4e49-91ad-1321261ed299
+    """
+    age_eff = age_effective_lindy(age_days, gm_tvl)
+    numerator = math.log(1.0 + LAF_DECAY_FACTOR_LAMBDA * age_eff)
+    denominator = math.log(1.0 + LAF_DECAY_FACTOR_LAMBDA * LAF_MAXIMUM_AGE_MONTHS)
+    return max(0.0, 1.0 - numerator / denominator)

{axis_synome-0.1.0.dev35 → axis_synome-0.1.0.dev36}/src/axis_synome.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev35
+Version: 0.1.0.dev36
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev35 → axis_synome-0.1.0.dev36}/src/axis_synome.egg-info/SOURCES.txt

@@ -33,7 +33,12 @@ src/axis_synome/spec/codegen_test/entities/agents.py
 src/axis_synome/spec/crypto_lending/__init__.py
 src/axis_synome/spec/crypto_lending/formulas/__init__.py
 src/axis_synome/spec/crypto_lending/formulas/lif.py
+src/axis_synome/spec/entities/__init__.py
+src/axis_synome/spec/entities/protocol_risk.py
 src/axis_synome/spec/risk_capital/__init__.py
+src/axis_synome/spec/risk_capital/lindy_factor.py
+src/axis_synome/spec/risk_capital/administrative_rrc/__init__.py
+src/axis_synome/spec/risk_capital/administrative_rrc/administrative_risk.py
 src/axis_synome/spec/risk_capital/financial_rrc/__init__.py
 src/axis_synome/spec/risk_capital/financial_rrc/entities.py
 src/axis_synome/spec/risk_capital/financial_rrc/perpetual_positions.py