Skip to content

Commit e3268a9

Browse files
taylorferrantaylorferran
authored
Merge pull request #22 from ssvlabs/sdk-updates
Sdk updates
2 parents 3c0ac54 + f9372d3 commit e3268a9

File tree

5 files changed

+236
-366
lines changed

5 files changed

+236
-366
lines changed

‎docs/based-applications/developers/BA-SDK/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@ It provides a set of functions for creating and managing based applications by i
1818
## Installation
1919

2020
```bash
21-
npm i @ssv-labs/based-apps-sdk
21+
npm i @ssv-labs/bapps-sdk
2222
```
2323

2424
## Example Usage
2525

2626
```typescript
27-
import { BasedAppsSDK } from "@ssv-labs/based-apps-sdk";
27+
import { BasedAppsSDK } from "@ssv-labs/bapps-sdk";
2828

2929
const sdk = new BasedAppsSDK({
3030
chain: 17000,

‎docs/based-applications/developers/BA-SDK/examples/participant-weight-example.md

Lines changed: 77 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -9,120 +9,93 @@ sidebar_position: 3
99
The script below uses the logic described in the [related section of the Based Application Development page](based-application-depvelopment.md/#3-participant-weight), fetching the data from the Based Application Subgraph, as well as the beacon chain (validator balance), via the `based-apps-sdk`, and returns the Weight for all Strategies that have opted in to a given Based Application. It then combines them with arbitrary logic, defined as a weighted harmonic mean, where validator balance is twice times more impactful than the ERC20 token.
1010

1111
```typescript
12-
import { BasedAppsSDK, chains } from "@ssv-labs/based-apps-sdk";
12+
import { BasedAppsSDK, chains } from "@ssv-labs/bapps-sdk";
1313

1414
const sdk = new BasedAppsSDK({
15-
chain: chains.holesky.id,
15+
chain: chains.holesky.id
1616
});
1717

1818
async function main(): Promise<void> {
19-
20-
/**
21-
****** Strategy-token risk-adjusted weights ******
22-
**/
19+
const tokenCoefficients = [
20+
{
21+
token: "0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f",
22+
coefficient: 5,
23+
},
24+
{
25+
token: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
26+
coefficient: 30,
27+
},
28+
];
29+
const validatorCoefficient = 1;
2330
// calculate strategy-token weights via the SDK
2431
const strategyTokenWeights = await sdk.api.calculateParticipantWeights({
25-
bAppId: "0x64714cf5db177398729e37627be0fc08f43b17a6",
32+
bAppId: "0xaA184b86B4cdb747F4A3BF6e6FCd5e27c1d92c5c",
2633
});
2734

28-
console.info(
29-
`Strategy-token weights: ${JSON.stringify(
30-
strategyTokenWeights,
31-
undefined,
32-
2
33-
)}`
34-
);
35-
36-
// Arbitrarily defined weights, the bApp has to decide these for themselves
37-
const validatorImportance = 1;
38-
const ssvTokenImportance = 2;
39-
40-
/**
41-
****** Combine with Arithmetic Weighted average ******
42-
**/
43-
console.info(`Using arithmetic weighted average to calculate Strategy weights.
44-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f`);
45-
46-
let simpleAverageStrategyWeights = new Map();
47-
for (const strategy of strategyTokenWeights) {
48-
// calculate the strategy weight, combining token weight and validator balance weight
49-
let strategyWeight =
50-
((strategy.validatorBalanceWeight || 0) * validatorImportance +
51-
strategy.tokenWeights[0].weight * ssvTokenImportance) /
52-
(validatorImportance + ssvTokenImportance);
53-
// set the value in the mapping
54-
simpleAverageStrategyWeights.set(strategy.id, strategyWeight);
35+
console.info(`Weight coefficient for Validator Balance is ${validatorCoefficient}`);
36+
for (let tokenCoefficient of tokenCoefficients){
37+
console.info(`Weight coefficient for token ${tokenCoefficient.token} is ${tokenCoefficient.coefficient}`);
5538
}
56-
57-
console.info(
58-
`Final Strategy weights: ${JSON.stringify(
59-
Object.fromEntries(simpleAverageStrategyWeights),
60-
undefined,
61-
2
62-
)}`
63-
);
64-
6539
/**
66-
****** Combine with harmonic weighted average ******
67-
**/
68-
console.info(`Using harmonic weighted average to calculate Strategy weights.
69-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f`);
70-
71-
// define the harmonic function
72-
const harmonic = (strategy) => {
73-
return (
74-
1 /
75-
((ssvTokenImportance / ssvTokenImportance + validatorImportance) /
76-
strategy.tokenWeights[0].weight +
77-
((validatorImportance / ssvTokenImportance + validatorImportance) /
78-
strategy.validatorBalanceWeight || 0))
79-
);
80-
};
81-
82-
let harmonicAverageStrategyWeights = new Map();
83-
// normalization coefficient
84-
let c_norm = strategyTokenWeights.reduce(
85-
(accumulator, strategy) => harmonic(strategy) + accumulator,
86-
0
40+
****** Combine with Arithmetic Weighted average ******
41+
**/
42+
console.info(`Using arithmetic weighted average to calculate Strategy weights.`);
43+
44+
let simpleAverageStrategyWeights = sdk.utils.calcSimpleStrategyWeights(
45+
strategyTokenWeights,
46+
{
47+
coefficients: tokenCoefficients,
48+
validatorCoefficient: validatorCoefficient,
49+
}
8750
);
88-
for (const strategy of strategyTokenWeights) {
89-
let strategyWeight = harmonic(strategy) / c_norm;
90-
// set the value in the mapping
91-
harmonicAverageStrategyWeights.set(strategy.id, strategyWeight);
92-
}
9351

9452
console.info(
9553
`Final Strategy weights: ${JSON.stringify(
96-
Object.fromEntries(harmonicAverageStrategyWeights),
54+
Object.fromEntries(simpleAverageStrategyWeights),
9755
undefined,
9856
2
9957
)}`
10058
);
101-
59+
10260
/**
103-
****** Combine with geometric average ******
104-
**/
105-
console.info(`Using weighted geometric average to calculate Strategy weights.
106-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f`);
107-
108-
let geometricAverageStrategyWeights = new Map();
109-
110-
for (const strategy of strategyTokenWeights) {
111-
let geom_numerator =
112-
2 * Math.log(strategy.tokenWeights[0].weight) +
113-
Math.log(strategy.validatorBalanceWeight || 0);
114-
let strategyWeight = Math.E ** (geom_numerator / 3);
115-
// set the value in the mapping
116-
geometricAverageStrategyWeights.set(strategy.id, strategyWeight);
117-
}
118-
119-
console.info(
120-
`Final Strategy weights: ${JSON.stringify(
121-
Object.fromEntries(geometricAverageStrategyWeights),
122-
undefined,
123-
2
124-
)}`
125-
);
61+
****** Combine with harmonic weighted average ******
62+
**/
63+
console.info(`Using harmonic weighted average to calculate Strategy weights`)
64+
65+
let harmonicAverageStrategyWeights = sdk.utils.calcHarmonicStrategyWeights(
66+
strategyTokenWeights,
67+
{
68+
coefficients: tokenCoefficients,
69+
validatorCoefficient: validatorCoefficient,
70+
})
71+
72+
console.info(
73+
`Final Strategy weights: ${JSON.stringify(
74+
Object.fromEntries(harmonicAverageStrategyWeights),
75+
undefined,
76+
2
77+
)}`
78+
);
79+
80+
/**
81+
****** Combine with geometric average ******
82+
**/
83+
console.info(`Using weighted geometric average to calculate Strategy weights.`);
84+
85+
let geometricAverageStrategyWeights = sdk.utils.calcGeometricStrategyWeights(
86+
strategyTokenWeights,
87+
{
88+
coefficients: tokenCoefficients,
89+
validatorCoefficient: validatorCoefficient,
90+
})
91+
92+
console.info(
93+
`Final Strategy weights: ${JSON.stringify(
94+
Object.fromEntries(geometricAverageStrategyWeights),
95+
undefined,
96+
2
97+
)}`
98+
);
12699
}
127100

128101
main();
@@ -131,22 +104,22 @@ main();
131104
It is pretty easy to spot the influence of the different functions on the combined risk-adjusted weight of each strategy in the results:
132105

133106
```sh
107+
Weight coefficient for Validator Balance is 1
108+
Weight coefficient for token 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f is 5
109+
Weight coefficient for token 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee is 30
134110
Using arithmetic weighted average to calculate Strategy weights.
135-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f
136111
Final Strategy weights: {
137-
"2": 0.28214396045721346,
138-
"10": 0.7178560395427865
112+
"19": 0.26242098843234996,
113+
"20": 0.7375790115676499,
139114
}
140-
Using harmonic weighted average to calculate Strategy weights.
141-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f
115+
Using harmonic weighted average to calculate Strategy weights
142116
Final Strategy weights: {
143-
"2": 0.19548130228618427,
144-
"10": 0.8045186977138158
117+
"19": 0.21998319135857475,
118+
"20": 0.7800168086414253,
145119
}
146120
Using weighted geometric average to calculate Strategy weights.
147-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f
148121
Final Strategy weights: {
149-
"2": 0.15539478660521727,
150-
"10": 0.6363452233105966
122+
"19": 0.2129838902493037,
123+
"20": 0.7296961242889372,
151124
}
152125
```

‎docs/based-applications/developers/README.md

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,15 @@ sidebar_position: 6
66

77
# Based Application Development
88

9-
This guide outlines the steps for based applications developers looking to build on the Based Applications platform.
9+
This guide outlines the steps for based applications developers looking to build on the Based Applications platform. Below is a diagram that summarizes the Based Applications development flow.
10+
11+
![Based Application Development Flow](/img/based-apps-developer-flow.png)
1012

1113
<!-- ## 0. Developing a Based Application Middleware smart contract
1214

1315
The `BAppManager` smart contract developed by SSV Labs accepts registrations of BApps that implement a specific interface. This is outlined [in this dedicated page](./smart-contracts/based-app-middleware-example.md), that also provides a simple example. -->
1416

17+
1518
## 1. Configuring and Registering the bApp
1619

1720
1. **Define core attributes**:
@@ -73,13 +76,13 @@ Based Application managers need to track the weight of each participant (strateg
7376
The first step is made fairly easier thanks to the `based-apps-sdk`, which needs to be installed first:
7477

7578
```sh
76-
npm i @ssv-labs/based-apps-sdk
79+
npm i @ssv-labs/bapps-sdk
7780
```
7881

7982
The SDK provides a function that returns all the risk-adjusted weights for each token, for all the strategies that opted in to a given bApp:
8083

8184
```ts
82-
import { BasedAppsSDK, chains } from "@ssv-labs/based-apps-sdk";
85+
import { BasedAppsSDK, chains } from "@ssv-labs/bapps-sdk";
8386
8487
const sdk = new BasedAppsSDK({
8588
chain: chains.holesky.id,
@@ -145,22 +148,32 @@ Note: this is a purely fictional scenario, to show the strong impact of the coef
145148
Below it's reported a code snippet, showing how to combine weights from step 1 using a simple arithmetic weighted average in the described scenario:
146149

147150
```ts
148-
const validatorImportance = 1;
149-
const ssvTokenImportance = 2;
150-
151-
console.info(`Using arithmetic weighted average to calculate Strategy weights.
152-
Validator Balance is 2 times more important than 0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f`);
153-
154-
let simpleAverageStrategyWeights = new Map();
155-
for (const strategy of strategyTokenWeights) {
156-
// calculate the strategy weight, combining token weight and validator balance weight
157-
let strategyWeight =
158-
((strategy.validatorBalanceWeight || 0) * validatorImportance +
159-
strategy.tokenWeights[0].weight * ssvTokenImportance) /
160-
(validatorImportance + ssvTokenImportance);
161-
// set the value in the mapping
162-
simpleAverageStrategyWeights.set(strategy.id, strategyWeight);
151+
const tokenCoefficients = [
152+
{
153+
token: "0x68a8ddd7a59a900e0657e9f8bbe02b70c947f25f",
154+
coefficient: 5,
155+
},
156+
// here you can specify additiona weights for additional tokens
157+
// {
158+
// token: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
159+
// coefficient: 30,
160+
// },
161+
];
162+
const validatorCoefficient = 1;
163+
164+
console.info(`Weight coefficient for Validator Balance is ${validatorCoefficient}`);
165+
for (let tokenCoefficient of tokenCoefficients){
166+
console.info(`Weight coefficient for token ${tokenCoefficient.token} is ${tokenCoefficient.coefficient}`);
163167
}
168+
console.info(`Using arithmetic weighted average to calculate Strategy weights.`);
169+
170+
let simpleAverageStrategyWeights = sdk.utils.calcSimpleStrategyWeights(
171+
strategyTokenWeights,
172+
{
173+
coefficients: tokenCoefficients,
174+
validatorCoefficient: validatorCoefficient,
175+
}
176+
);
164177

165178
console.info(
166179
`Final Strategy weights: ${JSON.stringify(

‎static/img/based-apps-developer-flow.png

1.13 MB
Loading

0 commit comments

Comments
 (0)