Skip to content

Commit cfc9bf8

Browse files
zsfelfoldifjl
zsfelfoldi
authored and
fjl
committed
[DOCS] add les API description (ethereum#20303)
1 parent a89f10f commit cfc9bf8

File tree

1 file changed

+318
-0
lines changed

1 file changed

+318
-0
lines changed

‎docs/_rpc/ns-les.md

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
---
2+
title: les Namespace
3+
sort_key: C
4+
---
5+
6+
The `les` API allows you to manage LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode.
7+
8+
* TOC
9+
{:toc}
10+
11+
### les_serverInfo
12+
13+
Get information about currently connected and total/individual allowed connection capacity.
14+
15+
| Client | Method invocation |
16+
|:--------|-------------------------------------------------------------|
17+
| Go | `les.ServerInfo() map[string]interface{}` |
18+
| Console | `les.serverInfo()` |
19+
| RPC | `{"method": "les_serverInfo", "params": []}` |
20+
21+
#### Example
22+
23+
```javascript
24+
> les.serverInfo
25+
{
26+
freeClientCapacity: 16000,
27+
maximumCapacity: 1600000,
28+
minimumCapacity: 16000,
29+
priorityConnectedCapacity: 180000,
30+
totalCapacity: 1600000,
31+
totalConnectedCapacity: 180000
32+
}
33+
```
34+
35+
### les_clientInfo
36+
37+
Get individual client information (connection, balance, pricing) on the specified list of clients or for all connected clients if the ID list is empty.
38+
39+
| Client | Method invocation |
40+
|:--------|---------------------------------------------------------------------------|
41+
| Go | `les.ClientInfo(ids []enode.ID) map[enode.ID]map[string]interface{}` |
42+
| Console | `les.clientInfo([id, ...])` |
43+
| RPC | `{"method": "les_clientInfo", "params": [[id, ...]]}` |
44+
45+
#### Example
46+
47+
```javascript
48+
> les.clientInfo([])
49+
{
50+
37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
51+
capacity: 16000,
52+
connectionTime: 11225.335901136,
53+
isConnected: true,
54+
pricing/balance: 998266395881,
55+
pricing/balanceMeta: "",
56+
pricing/negBalance: 501657912857,
57+
priority: true
58+
},
59+
6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
60+
capacity: 100000,
61+
connectionTime: 9874.839293082,
62+
isConnected: true,
63+
pricing/balance: 2908840710198,
64+
pricing/balanceMeta: "qwerty",
65+
pricing/negBalance: 206242704507,
66+
priority: true
67+
},
68+
740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
69+
capacity: 16000,
70+
connectionTime: 3089.286712188,
71+
isConnected: true,
72+
pricing/balance: 998266400174,
73+
pricing/balanceMeta: "",
74+
pricing/negBalance: 55135348863,
75+
priority: true
76+
},
77+
9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
78+
capacity: 16000,
79+
connectionTime: 11479.335479545,
80+
isConnected: true,
81+
pricing/balance: 998266452203,
82+
pricing/balanceMeta: "",
83+
pricing/negBalance: 564116425655,
84+
priority: true
85+
},
86+
ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
87+
capacity: 16000,
88+
connectionTime: 7095.794385419,
89+
isConnected: true,
90+
pricing/balance: 998266448492,
91+
pricing/balanceMeta: "",
92+
pricing/negBalance: 214617753229,
93+
priority: true
94+
},
95+
e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
96+
capacity: 16000,
97+
connectionTime: 8614.018237937,
98+
isConnected: true,
99+
pricing/balance: 998266391796,
100+
pricing/balanceMeta: "",
101+
pricing/negBalance: 185964891797,
102+
priority: true
103+
}
104+
}
105+
```
106+
107+
### les_priorityClientInfo
108+
109+
Get individual client information on clients with a positive balance in the specified ID range, `start` included, `stop` excluded. If `stop` is zero then results are returned until the last existing balance entry. `maxCount` limits the number of returned results. If the count limit is reached but there are more IDs in the range then the first missing ID is included in the result with an empty value assigned to it.
110+
111+
| Client | Method invocation |
112+
|:--------|----------------------------------------------------------------------------------------------------|
113+
| Go | `les.PriorityClientInfo(start, stop enode.ID, maxCount int) map[enode.ID]map[string]interface{}` |
114+
| Console | `les.priorityClientInfo(id, id, number)` |
115+
| RPC | `{"method": "les_priorityClientInfo", "params": [id, id, number]}` |
116+
117+
#### Example
118+
119+
```javascript
120+
> les.priorityClientInfo("0x0000000000000000000000000000000000000000000000000000000000000000", "0x0000000000000000000000000000000000000000000000000000000000000000", 100)
121+
{
122+
37078bf8ea160a2b3d129bb4f3a930ce002356f83b820f467a07c1fe291531ea: {
123+
capacity: 16000,
124+
connectionTime: 11128.247204027,
125+
isConnected: true,
126+
pricing/balance: 999819815030,
127+
pricing/balanceMeta: "",
128+
pricing/negBalance: 501657912857,
129+
priority: true
130+
},
131+
6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
132+
capacity: 100000,
133+
connectionTime: 9777.750592047,
134+
isConnected: true,
135+
pricing/balance: 2918549830576,
136+
pricing/balanceMeta: "qwerty",
137+
pricing/negBalance: 206242704507,
138+
priority: true
139+
},
140+
740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
141+
capacity: 16000,
142+
connectionTime: 2992.198001116,
143+
isConnected: true,
144+
pricing/balance: 999819845102,
145+
pricing/balanceMeta: "",
146+
pricing/negBalance: 55135348863,
147+
priority: true
148+
},
149+
9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {
150+
capacity: 16000,
151+
connectionTime: 11382.246766963,
152+
isConnected: true,
153+
pricing/balance: 999819871598,
154+
pricing/balanceMeta: "",
155+
pricing/negBalance: 564116425655,
156+
priority: true
157+
},
158+
ce65ada2c3e17d6da00cec0b3cc4c8ed5e74428b60f42fa287eaaec8cca62544: {
159+
capacity: 16000,
160+
connectionTime: 6998.705683407,
161+
isConnected: true,
162+
pricing/balance: 999819882177,
163+
pricing/balanceMeta: "",
164+
pricing/negBalance: 214617753229,
165+
priority: true
166+
},
167+
e1495ceb6db842f3ee66428d4bb7f4a124b2b17111dae35d141c3d568b869ef1: {
168+
capacity: 16000,
169+
connectionTime: 8516.929533901,
170+
isConnected: true,
171+
pricing/balance: 999819891640,
172+
pricing/balanceMeta: "",
173+
pricing/negBalance: 185964891797,
174+
priority: true
175+
}
176+
}
177+
178+
> les.priorityClientInfo("0x4000000000000000000000000000000000000000000000000000000000000000", "0xe000000000000000000000000000000000000000000000000000000000000000", 2)
179+
{
180+
6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77: {
181+
capacity: 100000,
182+
connectionTime: 9842.11178361,
183+
isConnected: true,
184+
pricing/balance: 2912113588853,
185+
pricing/balanceMeta: "qwerty",
186+
pricing/negBalance: 206242704507,
187+
priority: true
188+
},
189+
740c78f7d914e5c763731bc751b513fc2388ffa0b47db080ded3e8b305e68c75: {
190+
capacity: 16000,
191+
connectionTime: 3056.559199029,
192+
isConnected: true,
193+
pricing/balance: 998790060237,
194+
pricing/balanceMeta: "",
195+
pricing/negBalance: 55135348863,
196+
priority: true
197+
},
198+
9985ade55b515f79f64274bf2ae440ca8c433cfb0f283fb6010bf46f796b2a3b: {}
199+
}
200+
```
201+
202+
### les_addBalance
203+
204+
Add signed value to the token balance of the specified client and update its `meta` tag. The balance cannot go below zero or over `2^^63-1`. The balance values before and after the update are returned. The `meta` tag can be used to store a sequence number or reference to the last processed incoming payment, token expiration info, balance in other currencies or any application-specific additional information.
205+
206+
| Client | Method invocation |
207+
|:--------|-----------------------------------------------------------------------------------|
208+
| Go | `les.AddBalance(id enode.ID, value int64, meta string) ([2]uint64, error)}` |
209+
| Console | `les.addBalance(id, number, string)` |
210+
| RPC | `{"method": "les_addBalance", "params": [id, number, string]}` |
211+
212+
#### Example
213+
214+
```javascript
215+
> les.addBalance("0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77", 1000000000, "qwerty")
216+
[968379616, 1968379616]
217+
```
218+
219+
### les_setClientParams
220+
221+
Set capacity and pricing factors for the specified list of connected clients or for all connected clients if the ID list is empty.
222+
223+
| Client | Method invocation |
224+
|:--------|-----------------------------------------------------------------------------------|
225+
| Go | `les.SetClientParams(ids []enode.ID, params map[string]interface{}) error` |
226+
| Console | `les.setClientParams([id, ...], {string: value, ...})` |
227+
| RPC | `{"method": "les_setClientParams", "params": [[id, ...], {string: value, ...}]}` |
228+
229+
#### Example
230+
231+
```javascript
232+
> les.setClientParams(["0x6a47fe7bb23fd335df52ef1690f37ab44265a537b1d18eb616a3e77f898d9e77"], {
233+
"capacity": 100000,
234+
"pricing/timeFactor": 0,
235+
"pricing/capacityFactor": 1000000000,
236+
"pricing/requestCostFactor": 1000000000,
237+
"pricing/negative/timeFactor": 0,
238+
"pricing/negative/capacityFactor": 1000000000,
239+
"pricing/negative/requestCostFactor": 1000000000,
240+
})
241+
null
242+
```
243+
244+
### les_setDefaultParams
245+
246+
Set default pricing factors for subsequently connected clients.
247+
248+
| Client | Method invocation |
249+
|:--------|-----------------------------------------------------------------------------------|
250+
| Go | `les.SetDefaultParams(params map[string]interface{}) error` |
251+
| Console | `les.setDefaultParams({string: value, ...})` |
252+
| RPC | `{"method": "les_setDefaultParams", "params": [{string: value, ...}]}` |
253+
254+
#### Example
255+
256+
```javascript
257+
> les.setDefaultParams({
258+
"pricing/timeFactor": 0,
259+
"pricing/capacityFactor": 1000000000,
260+
"pricing/requestCostFactor": 1000000000,
261+
"pricing/negative/timeFactor": 0,
262+
"pricing/negative/capacityFactor": 1000000000,
263+
"pricing/negative/requestCostFactor": 1000000000,
264+
})
265+
null
266+
```
267+
268+
### les_latestCheckpoint
269+
270+
Get the index and hashes of the latest known checkpoint.
271+
272+
| Client | Method invocation |
273+
|:--------|-------------------------------------------------------------|
274+
| Go | `les.LatestCheckpoint() ([4]string, error)` |
275+
| Console | `les.latestCheckpoint()` |
276+
| RPC | `{"method": "les_latestCheckpoint", "params": []}` |
277+
278+
#### Example
279+
280+
```javascript
281+
> les.latestCheckpoint
282+
["0x110", "0x6eedf8142d06730b391bfcbd32e9bbc369ab0b46ae226287ed5b29505a376164", "0x191bb2265a69c30201a616ae0d65a4ceb5937c2f0c94b125ff55343d707463e5", "0xf58409088a5cb2425350a59d854d546d37b1e7bef8bbf6afee7fd15f943d626a"]
283+
```
284+
285+
### les_getCheckpoint
286+
287+
Get checkpoint hashes by index.
288+
289+
| Client | Method invocation |
290+
|:--------|-------------------------------------------------------------|
291+
| Go | `les.GetCheckpoint(index uint64) ([3]string, error)` |
292+
| Console | `les.getCheckpoint(number)` |
293+
| RPC | `{"method": "les_getCheckpoint", "params": [number]}` |
294+
295+
#### Example
296+
297+
```javascript
298+
> les.getCheckpoint(256)
299+
["0x93eb4af0b224b1097e09181c2e51536fe0a3bf3bb4d93e9a69cab9eb3e28c75f", "0x0eb055e384cf58bc72ca20ca5e2b37d8d4115dce80ab4a19b72b776502c4dd5b", "0xda6c02f7c51f9ecc3eca71331a7eaad724e5a0f4f906ce9251a2f59e3115dd6a"]
300+
```
301+
302+
### les_getCheckpointContractAddress
303+
304+
Get the address of the checkpoint oracle contract.
305+
306+
| Client | Method invocation |
307+
|:--------|-------------------------------------------------------------------|
308+
| Go | `les.GetCheckpointContractAddress() (string, error)` |
309+
| Console | `les.checkpointContractAddress()` |
310+
| RPC | `{"method": "les_getCheckpointContractAddress", "params": []}` |
311+
312+
#### Example
313+
314+
```javascript
315+
> les.checkpointContractAddress
316+
"0x9a9070028361F7AAbeB3f2F2Dc07F82C4a98A02a"
317+
```
318+

0 commit comments

Comments
 (0)