docs progress, api docs

jito-foundation · Aug 20, 2024 · 9fa8b58 · 9fa8b58
1 parent d65a8ad
commit 9fa8b58
Show file tree

Hide file tree

Showing 9 changed files with 182 additions and 105 deletions.
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -8,6 +8,9 @@
     {% seo %}
     <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
     {% include head-custom.html %}
+
+    <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
+    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
 </head>
 <body>
 <div class="container-lg px-3 my-5 markdown-body">
@@ -64,5 +67,15 @@ <h1><a href="{{ "/" | absolute_url }}">{{ site.title }}</a></h1>
         wrapper.appendChild(el.parentNode);
     });
 </script>
+
+<script>
+    MathJax = {
+      tex: {
+        inlineMath: [['$', '$'], ['\\(', '\\)']],
+        displayMath: [['$$', '$$'], ['\\[', '\\]']],
+        processEscapes: true
+      }
+    };
+    </script>
 </body>
 </html>
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,100 @@
+---
+layout: default
+title: Steward API Documentation
+---
+
+# Steward API Documentation
+
+## Events Endpoint
+
+This endpoint allows you to retrieve various events related to the Steward program. Events are emitted by the Steward program when certain actions occur, such as when a validator is scored, or when rebalancing takes place.
+
+### Endpoint
+
+GET https://kobe.mainnet.jito.network/api/v1/steward_events
+
+### Parameters
+
+| Parameter    | Type    | Required | Description                                         |
+| ------------ | ------- | -------- | --------------------------------------------------- |
+| vote_account | String  | No       | Filter events by validator vote account public key  |
+| epoch        | Integer | No       | Filter events by epoch number                       |
+| event_type   | String  | No       | Filter events by type (see Valid Event Types below) |
+| page         | Integer | No       | Page number for pagination (default: 1)             |
+| limit        | Integer | No       | Number of events per page (default: 100, max: 1000) |
+
+### Valid Event Types
+
+Most relevant to validators:
+
+- `ScoreComponents`: Validator scoring details. Emitted once every 10 epochs
+- `InstantUnstakeComponents`: Information about instant unstaking events
+- `RebalanceEvent`: Details about stake rebalancing operations
+
+Updates to overall state:
+
+- `StateTransition`: Changes in the Steward program's state machine
+- `DecreaseComponents`: Included in RebalanceEvent, provides specifics on stake decreases
+- `AutoRemoveValidatorEvent`: Automatic removal of offline validators from the pool
+- `AutoAddValidatorEvent`: Automatic addition of new validators to the pool
+- `EpochMaintenanceEvent`: Epoch maintenance operations
+
+### Example Request: Get a validator's scores
+
+GET https://kobe.mainnet.jito.network/api/v1/steward_events?vote_account=J1to3PQfXidUUhprQWgdKkQAMWPJAEqSJ7amkBDE9qhF&event_type=ScoreComponents
+
+```json
+{
+  "events": [
+  {
+    "signature": "5N3hVRpuqsiXCiChrm3GuaWRfi2zZMYAkx6jnM3YTocAC5RBTsrukk4ghFHeCyZawC7Ca72i7fo8TNg2MsG1zXP7",
+    "event_type": "ScoreComponents",
+    "vote_account": "J1to3PQfXidUUhprQWgdKkQAMWPJAEqSJ7amkBDE9qhF",
+    "timestamp": "2024-08-20T06:18:46Z",
+    "data": {
+      "score": 0.9763466522227435,
+      "yield_score": 0.9763466522227435,
+      "mev_commission_score": 1.0,
+      "blacklisted_score": 1.0,
+      "superminority_score": 1.0,
+      "delinquency_score": 1.0,
+      "running_jito_score": 1.0,
+      "commission_score": 1.0,
+      "historical_commission_score": 1.0,
+      "vote_credits_ratio": 0.9763466522227435
+    },
+    "epoch": 659
+  },
+  ...
+  ]
+}
+```
+
+### Example Request: See stake movements by epoch
+
+`GET https://kobe.mainnet.jito.network/api/v1/steward_events?event_type=RebalanceEvent&epoch=657&limit=2000`
+
+```json
+{
+  "events": [
+    {
+      "signature": "64GGjM2QtrKw4SPocR5hmw17Kenf9qBdRRM5KrrM9gkr8XUgyyjXNQkuzfxq3ZhDJgHU8jvhUKxaAfMnnGp85Uss",
+      "event_type": "RebalanceEvent",
+      "vote_account": "7emL18Bnve7wbYE9Az7vYJjikxN6YPU81igf6rVU5FN8",
+      "timestamp": "2024-08-17T20:20:57Z",
+      "data": {
+        "rebalance_type_tag": "Increase",
+        "increase_lamports": 2762842586176,
+          "decrease_components": {
+          "scoring_unstake_lamports": 0,
+          "instant_unstake_lamports": 0,
+          "stake_deposit_unstake_lamports": 0,
+          "total_unstake_lamports": 0
+        }
+      },
+      "epoch": 657
+    },
+    ...
+  ]
+}
+```
diff --git a/docs/cli.md b/docs/cli.md
@@ -310,46 +310,3 @@ Marked for immediate removal: false
 ```bash
 ./target/release/steward-cli --program-id Stewardf95sJbmtcZsyagb2dg4Mo8eVQho8gpECvLx8 close-steward --steward-config jitoVjT9jRUyeXHzvCwzPgHj7yWNRhLcUoXtes4wtjv --authority-keypair-path ../../credentials/stakenet_test.json
 ```
-
-# Deploy and Upgrade
-
-- upgrade solana cli to 1.18.16
-- create a new keypair: `solana-keygen new -o credentials/temp-buffer.json`
-- use anchor `0.30.0`: `avm install 0.30.0 && avm use 0.30.0`
-- make sure your configured keypair is program authority
-- build .so file: `anchor build --no-idl`
-- Write to buffer: `solana program write-buffer --use-rpc --buffer credentials/temp-buffer.json --with-compute-unit-price 10000 --max-sign-attempts 10000 target/deploy/jito_steward.so --keypair credentials/stakenet_test.json`
-- Upgrade: `solana program upgrade $(solana address --keypair credentials/temp-buffer.json) Stewardf95sJbmtcZsyagb2dg4Mo8eVQho8gpECvLx8 --keypair credentials/stakenet_test.json`
-- Close Buffers: `solana program close --buffers --keypair credentials/stakenet_test.json`
-- Upgrade Program Size: `solana program extend Stewardf95sJbmtcZsyagb2dg4Mo8eVQho8gpECvLx8 1000000 --keypair credentials/stakenet_test.json`
-
-# Initial Parameters
-
-```bash
-# Note - Do not use this .env when updating the parameters - this will update them all
-MEV_COMMISSION_RANGE=10
-EPOCH_CREDITS_RANGE=30
-COMMISSION_RANGE=30
-MEV_COMMISSION_BPS_THRESHOLD=1000
-COMMISSION_THRESHOLD=5
-HISTORICAL_COMMISSION_THRESHOLD=50
-SCORING_DELINQUENCY_THRESHOLD_RATIO=0.85
-INSTANT_UNSTAKE_DELINQUENCY_THRESHOLD_RATIO=0.70
-NUM_DELEGATION_VALIDATORS=200
-SCORING_UNSTAKE_CAP_BPS=750
-INSTANT_UNSTAKE_CAP_BPS=1000
-STAKE_DEPOSIT_UNSTAKE_CAP_BPS=1000
-COMPUTE_SCORE_SLOT_RANGE=1000
-INSTANT_UNSTAKE_EPOCH_PROGRESS=0.50
-INSTANT_UNSTAKE_INPUTS_EPOCH_PROGRESS=0.50
-NUM_EPOCHS_BETWEEN_SCORING=3
-MINIMUM_STAKE_LAMPORTS=100000000000
-MINIMUM_VOTING_EPOCHS=5
-```
-
-# Getting Ready to Merge
-
-```bash
-cargo +nightly-2024-02-04 clippy --all-features --all-targets --tests -- -D warnings
-anchor build --idl idl
-```
diff --git a/docs/index.md b/docs/index.md
@@ -13,27 +13,12 @@ The core operations of the Steward Program are permissionless such that any cran
 
 ## Table of Contents
 
-1. [Program Overview](program-overview.md)
-2. [State Machine](state-machine.md)
-3. [Validator Management](validator-management.md)
-4. [Admin Abilities](admin-abilities.md)
-5. [Parameters](parameters.md)
-
-6. Validators
-
-   - [Scoring System](validators/scoring-system.md)
-   - [Instant Unstaking](validators/instant-unstaking.md)
-   - [Eligibility Criteria](validators/eligibility-criteria.md)
-
-7. Developers
-
+1. [Terminology](./terminology.md)
+2. [Program Overview](program-overview.md)
+3. [Parameters](parameters.md)
+4. [Command-line interface](./cli.md)
+5. [Events API](./api.md)
+6. [StakeNet UI](./ui.md)
+7. Advanced
    - [SPL Stake Pool Internals](developers/spl-stake-pool-internals.md)
    - [Validator States](developers/validator-states.md)
-   - [Program Architecture](developers/program-architecture.md)
-   - [Integration Guide](developers/integration-guide.md)
-
-8. [Appendix](appendix.md)
-
-For validators interested in understanding how they are scored and managed within the Steward Program, please refer to the Validators section.
-
-For developers interested in the technical details of the Steward Program, please refer to the Developers section.
diff --git a/docs/program-overview.md b/docs/program-overview.md
@@ -54,7 +54,7 @@ In this version 0 of the score formula, there is no weighting of any factor abov
 
 For a breakdown of the formulas used for each score, see the Appendix.
 
-Take a look at the implementation in [score.rs](./src/score.rs#L14)
+Take a look at the implementation in [score.rs](https://github.com/jito-foundation/stakenet/blob/master/programs/steward/src/score.rs#L14)
 
 ### Compute Delegations
 
@@ -86,7 +86,7 @@ let instant_unstake =
     delinquency_check || commission_check || mev_commission_check || is_blacklisted;
 ```
 
-Take a look at the implementation in [score.rs](./src/score.rs#L212)
+Take a look at the implementation in [score.rs](https://github.com/jito-foundation/stakenet/blob/master/programs/steward/src/score.rs#L212)
 
 ### Rebalance
 

diff --git a/docs/ui.md b/docs/ui.md
diff --git a/docs/validators/instant-unstaking.md b/docs/validators/instant-unstaking.md
@@ -5,4 +5,4 @@ title: Instant Unstaking
 
 # Instant Unstaking
 
-[Detailed description of the instant unstaking process goes here]
+[Detailed description of the instant unstaking process in progress. For now, see Program Overview.]
diff --git a/docs/validators/rebalancing.md b/docs/validators/rebalancing.md
@@ -1,8 +1,8 @@
 ---
 layout: default
-title: Scoring System
+title: Rebalance System
 ---
 
-# Scoring System
+# Rebalance System
 
-[In-depth explanation of the scoring system with visuals goes here]
+[In-depth explanation of the rebalance system in progress. For now, see Program Overview.]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,4 +5,4 @@ title: Instant Unstaking

		# Instant Unstaking

		[Detailed description of the instant unstaking process goes here]
		[Detailed description of the instant unstaking process in progress. For now, see Program Overview.]