doc: docs update

Author: kupermind

README.md

@@ -26,7 +26,7 @@ while maintaining exposure to staking rewards.
 
 ### L2 Layer (i.e. Base, etc)
 - **StakingManager**: Orchestrates service deployment and staking operations
-- **ExternalStakingDistributor**: Performs service deployment and staking for external staking contracts
+- **ExternalStakingDistributor**: Manages external staking on third-party staking proxies — deploys services (creates Safe multisigs with self as module), stakes/unstakes/re-stakes, claims and distributes rewards (split between Collector, protocol, and curating agent per configurable reward factors). Supports V1 (rewards on multisig) and V2 (rewards on contract) staking types. Access-controlled via owner, managing agents (unstakes), and per-proxy curating agents with staking guards
 - **StakingTokenLocked**: Manages individual staking instances and reward distribution
 - **ActivityModule**: Handles service activity verification and reward claiming
 - **Collector**: Collects and bridges rewards back to L1
@@ -49,7 +49,7 @@ contracts/
 │   └── UnstakeRelayer.sol # Unstake request handling
 ├── l2/                    # L2 (Gnosis Chain) contracts
 │   ├── StakingManager.sol    # Staking orchestration
-│   ├── ExternalStakingDistributor # External staking orchestration
+│   ├── ExternalStakingDistributor.sol # External staking orchestration
 │   ├── StakingTokenLocked.sol # Individual staking instances
 │   ├── ActivityModule.sol     # Service activity management
 │   └── Collector.sol          # Reward collection and bridging
@@ -80,7 +80,7 @@ doc/                       # Documentation and whitepaper
 1. Services are deployed on L2 with OLAS backing
 2. Rewards accumulate based on service performance
 3. ActivityModule verifies service liveness and required KPI performance
-4. ExternalStakingDistributor curates all external staking and forces unstakes, if required
+4. ExternalStakingDistributor curates external staking on third-party proxies: deploys services via Safe multisigs, stakes them, claims rewards (split between Collector, protocol, and curating agents per configurable factors), and forces unstakes for underperformers or when rewards are zero/service is evicted
 5. Collector gathers rewards and bridges them back to L1 via a Distributor contract
 
 ### 3. Withdrawal Process

doc/agent-workflow.md

@@ -156,6 +156,31 @@ if ((stakingProxy.getNumServiceIds() > 0) && (block.timestamp - stakingProxy.tsC
 This check is going to skip the `checkpoint()` call if no agents are staked or if the checkpoint has been already
 triggered within the `livenessPeriod` time.
 
+### External Staking (ExternalStakingDistributor)
+
+The [ExternalStakingDistributor](../contracts/l2/ExternalStakingDistributor.sol) manages staking on third-party staking proxy contracts. It deploys services (creating Safe multisigs with itself as module), stakes/unstakes/re-stakes them, and claims and distributes rewards.
+
+**Staking:** Whitelisted curating agents (or the owner) call `stake()` to deploy a service on a whitelisted staking proxy. The contract creates a Safe multisig, registers it as a service, and stakes it. The curating agent is recorded per service.
+
+**Claiming rewards:** Agents call `claim()` with arrays of staking proxies and service Ids. Rewards are distributed according to per-proxy configurable factors (must sum to 100%):
+- **Collector share** — sent to Collector via `topUpBalance(amount, REWARD)` for L1 bridging
+- **Protocol share** — sent to Collector via `topUpProtocol(amount)` for protocol use
+- **Curating agent share** — transferred directly to the curating agent address
+
+For V1 staking types, rewards land on the service multisig and are distributed via `execTransactionFromModule`. For V2 staking types, rewards land directly on the contract.
+
+**Unstaking:** Managing agents (or the owner) call `unstakeAndWithdraw()` to unstake a service, distribute remaining rewards, and optionally fulfill pending withdraw requests through Collector. Anyone can trigger unstake if the staking proxy has zero available rewards or if the service is evicted.
+
+**Re-staking:** If a service is evicted, curating agents, managing agents, or the owner can call `reStake()` to unstake and immediately re-stake it.
+
+Events to track external staking activity:
+```solidity
+event ExternalServiceStaked(address indexed sender, address indexed stakingProxy, uint256 indexed serviceId, uint256 agentId, bytes32 configHash, uint256 stakingDeposit, uint256 stakedBalance);
+event ExternalServiceUnstaked(address indexed sender, address indexed stakingProxy, uint256 indexed serviceId, uint256 stakingDeposit, uint256 stakedBalance);
+event ExternalServiceRestaked(address indexed sender, address indexed stakingProxy, uint256 indexed serviceId);
+event Claimed(address[] stakingProxies, uint256[] serviceIds, uint256[] rewards);
+```
+
 ### Trigger L2 to L1 Tokens Bridging
 
 Each L2 [Collector](../contracts/l2/Collector.sol) proxy contract collects OLAS from **REWARD** / **UNSTAKE** / **UNSTAKE_RETIRED**

doc/architecture-diagrams.md

@@ -24,6 +24,7 @@ flowchart LR
 
   subgraph L2 [L2 — Gnosis, Base]
     SM[StakingManager]
+    ESD[ExternalStakingDistributor]
     STL[StakingTokenLocked]
     Coll[Collector]
     Svc[Services]
@@ -54,6 +55,10 @@ flowchart LR
   A-->|claim|AM
   AM-->|claim|SM
   AM-->|controls|Svc
+  BP2 -->|deposit OLAS| ESD
+  ESD -->|stake / unstake / re-stake| Svc
+  ESD -->|claim rewards| Svc
+  ESD -->|distribute rewards| Coll
 
   %% C) Withdraw & Unstake (UNSTAKE → Treasury)
   U -->|request to withdraw and finalize| T
@@ -86,6 +91,7 @@ sequenceDiagram
   participant UR as UnstakeRelayer
   participant BP1 as Bridge (L1)
   participant SM as StakingManager
+  participant ESD as ExternalStakingDistributor
   participant STL as StakingTokenLocked
   participant Coll as Collector
   participant S as Services
@@ -109,6 +115,14 @@ sequenceDiagram
   Dist->>V: top up vault balance
   Dist-->>V: optional lock to veOLAS
 
+  %% B2) External Staking (ExternalStakingDistributor)
+  BP1->>ESD: deposit OLAS (via L2 staking processor)
+  ESD->>S: deploy service (create Safe multisig, stake)
+  S->>ESD: rewards accrue
+  ESD->>ESD: claim & distribute rewards
+  ESD->>Coll: collector share (topUpBalance REWARD)
+  ESD->>Coll: protocol share (topUpProtocol)
+
   %% C) Withdraw with possible shortfall (UNSTAKE -> Treasury)
   U->>T: request withdraw
   T->>V: redeem up to vault+reserve
@@ -142,7 +156,8 @@ sequenceDiagram
 - **UnstakeRelayer** — receives **UNSTAKE_RETIRED** returns and forwards to `stOLAS.topUpRetiredBalance` (does not directly fund Treasury payouts).
 
 **L2 components**
-- **StakingManager / StakingTokenLocked** — manage staking lifecycle for services and accrue rewards.
+- **StakingManager / StakingTokenLocked** — manage internal staking lifecycle for LST services and accrue rewards.
+- **ExternalStakingDistributor** — manages external staking on third-party staking proxies. Deploys services (creates Safe multisigs with self as module), stakes/unstakes/re-stakes, claims and distributes rewards split between Collector (for L1 bridging), protocol (`topUpProtocol`), and curating agents per configurable reward factors (must sum to 100%). Supports V1 (rewards on multisig) and V2 (rewards on contract) staking types. Access control: owner, whitelisted managing agents (unstakes), per-proxy curating agents with staking guards. Receives OLAS from L2 staking processor (`deposit`) and handles withdraw/unstake requests back through Collector (`withdrawAndRequestUnstake`, `unstakeAndWithdraw`).
 - **Collector** — bridges ops/tokens to L1 with explicit routing for: **REWARD**, **UNSTAKE**, **UNSTAKE_RETIRED**.
 
 **Bridge Processor (L1/L2)** — abstract transport for messages + OLAS between chains.

doc/architecture.md

@@ -18,7 +18,9 @@ It is meant to accompany `README.md` and serve as a quick reference for develope
 - **`UnstakeRelayer`** — handles returns of permanently closed staking model unstakes; tops up `stOLAS` with retired reserves.
 
 **L2 (Gnosis, Base, etc.):**
-- **`StakingManager` / `ExternalStakingDistributor` / `StakingTokenLocked`** — staking logic for services, accrual of rewards, initiation of stake and unstake.
+- **`StakingManager`** — orchestrates internal service deployment/staking for LST-managed services.
+- **`ExternalStakingDistributor`** — manages external staking on third-party staking proxies. Deploys services by creating Safe multisigs (with self as module), stakes/unstakes/re-stakes services, claims rewards and distributes them (split between Collector for L1 bridging, protocol via `topUpProtocol`, and curating agent per configurable reward factors). Supports two staking types: V1 (rewards land on service multisig, distributed via `execTransactionFromModule`) and V2 (rewards land directly on the contract). Access control: owner can do everything; whitelisted **managing agents** can force unstakes; per-proxy **curating agents** (guarded by a **staking guard** address) can stake. Receives OLAS deposits from L2 staking processor and handles withdraw/unstake requests back through Collector.
+- **`StakingTokenLocked`** — restricted StakingToken that only allows StakingManager as staker.
 - **`Collector`** — bridge intermediary: routes collected tokens back to L1.
 
 **Bridging Processors:**