Direct RC delegation documentation
# Direct RC delegations
## Forewords:
You may have heard about RC pools, direct RC delegations are **not** the same. RC pools got deprecated in favor of RC delegations. Although they are quite similar in name, their function is very different. If you're interested in the difference between the two see this post: https://peakd.com/rc/@howo/direct-rc-delegations-vs-rc-pools-and-tentative-direct-rc-delegations-spec
## Direct RC delegations
Direct RC delegations are the simplest version of RC delegation you can think of:
Bob is out of RC, Alice has 200 RC, so she uses her posting key to delegate 100 RC to Bob. Bob now has 100 rc that he is free to use.
Now while this is a basic example, I'll dive into some more specifics.
### Max RC vs RC
It's important to differentiate between the two resources we are dealing with: 
Here I have 77 million RC out of 87 million **max** RC. When a user executes a direct RC delegation, they delegate **max** RC. This has two effects:
- Once spent, the delegated RC will regenerate on the delegatee's account
- Delegating RC will increase the amount of RC you regenerate. The more max RC you have the more you regenerate RC over time, in theory you could delegate 100 million RC on someone with 10k RC to make him regenerate his RC much more quickly and then undelegate. (Although this is unpractical due to the fact that undelegating burns unspent RC).
### Constraints & details
- You cannot delegate delegated RC, this is to avoid expensive chain computations.
- You delegate max RC **and** RC, so you can't do a delegation when you are out of RC.
- When undelegating, the delegator only gets his max RC back, all unspent RC is burned. The delegator will regenerate the RC over time.
- Delegating is done over `custom_json` and requires posting authority (more on that later)
- You can delegate to as many accounts as you want.
- You can't delegate all your RC (and end up with 0 RC), you have to always keep the RC equivalent of the account creation fee (3 HIVE as the time of writing).
- You can delegate up to 100 accounts in a single operation.
### RC reserve
When an account is created, the `account_creation_fee` is burned (as the time of writing, 3 HIVE), that amount is converted in RC, this is why even 0 HP account have some RC. (this is also true for accounts created with account creation tokens).
This "RC reserve" is not delegatable, this is to prevent a bad actor from delegating all your RC away effectively soft-locking your account.
## RC delegations in action
There is only one operation used for everything. `delegate_rc` the operations is sent in the form a custom json, here's an example where `howo` delegates 100 max RC to `alice`.
```
{
"id": "rc",
"json": [
"delegate_rc",
{
"from": "howo",
"delegatees": [
"alice"
],
"max_rc": 100
}
]
}
```
I will be basing the rest of this guide using hive-js, all the examples, also note that all the keys in this example are from a testnet, they are worthless.
### Creating an RC delegation
The parameters are pretty straightforward:
from: Person who delegates the max RC
`delegatees`: array of account names that you want to delegate to (max 100)
`max_rc`: max RC amount you want to delegate.
```
function delegate_rc(delegator, posting_key, delegatees, max_rc) {
return new Promise(resolve => {
const json = JSON.stringify(['delegate_rc', {
from: delegator,
delegatees: delegatees,
max_rc: max_rc,
}]);
hive.broadcast.customJson(posting_key, [], [delegator], 'rc', json, function (err, result) {
resolve(err)
});
});
}
```
### Updating a delegation
Updating a delegation is done with the same operation, just input a different max RC amount and the delegation will be increased/reduced.
Keep in mind that if you reduce the delegation, the max RC will come back to you but the RC will be burned.
### Deleting a delegation
Deleting a delegation is done by calling delegate_rc with `max_rc` set to 0.
### Getting RC from an account
This api endpoint has existed since HF20 but has been updated with RC delegations, it's simply called by passing in an array of accounts
```
function get_rc(accounts) {
return new Promise(resolve => {
hive.api.call('rc_api.find_rc_accounts', {accounts: accounts}, function (err, result) {
return resolve(result)
})
});
}
async function main() {
let rc_accounts = await get_rc(["initminer", "miners"])
}
```
output is an array of `rc_account` objects, note the new fields: `delegated_rc` and `received_delegated_rc`
```
[
{
"account": "initminer",
"rc_manabar": {
"current_mana": 3153959569,
"last_update_time": 1660535262
},
"max_rc_creation_adjustment": {
"amount": "2020748973",
"precision": 6,
"nai": "@@000000037"
},
"max_rc": 3153959569,
"delegated_rc": 150,
"received_delegated_rc": 0
},
{
"account": "miners",
"rc_manabar": {
"current_mana": 2020748983,
"last_update_time": 1660535259
},
"max_rc_creation_adjustment": {
"amount": "2020748973",
"precision": 6,
"nai": "@@000000037"
},
"max_rc": 2020748983,
"delegated_rc": 0,
"received_delegated_rc": 10
}
]
```
### Listing RC accounts:
If you don't have the full list, you can request the RC accounts:
```
function list_rc_accounts(start, limit) {
return new Promise(resolve => {
hive.api.call('rc_api.list_rc_accounts', {start:start, limit: limit}, function (err, result) {
return resolve(result)
})
});
}
async function main() {
let rc_accounts = await list_rc_accounts("initminer", 2)
}
```
The ordering is alphabetical, so you input the start and how many users you want to fetch (limited to 1000) and there you go, think of it as pagination.
If you reach the end of the 1000 and didn't find your account, put the last account as "start" and get the next 1000.
### Listing all delegations
So this is where it gets a tad tricky, the `start` param is an array.
- The first element of the array is `from`, who is delegating
- The second element of the array is `to`, who is delegated to
The second parameter, `limit` is pretty self explanatory. it's limited to 1000 elements per query.
Both parameters are used for pagination.
If you want to fetch a specific delegation, fill both `from` and `to`
If you want to get all the delegations from an account, set `from` as the account and leave `to` as empty
If you only input `from` and reach the end of `limit` (for instance if an account delegated more than 1000 users), you can continue by inputting the last delegatee in the `to` field.
Here's a few examples:
```
function list_rc_direct_delegations(from, to, limit) {
return new Promise(resolve => {
hive.api.call('rc_api.list_rc_direct_delegations', {start:[from, to], limit: limit}, function (err, result) {
return resolve(result)
})
});
}
async function main() {
// List the first 100 delegations from initminer
await list_rc_direct_delegations("initminer", "", 100)
// get the delegation from initminer to howo
await list_rc_direct_delegations("initminer", "howo", 1)
// List 100 delegations starting with the initminer -> howo delegation
await list_rc_direct_delegations("initminer", "howo", 100)
}
```
The output is an array of delegation objects:
```
[
{
"from": "initminer",
"to": "howo",
"delegated_rc": 70
},
{
"from": "initminer",
"to": "alice",
"delegated_rc": 70
}
]
```
**Important** tidbit about the ordering, you may be confused that this list is not in alphabetical order, this is because under the hood, we index with account numbers, not account names.
So the reason why `howo` comes up before `alice` in this testnet, is because if you look at the get_account api call:
```
[{
"id": 6,
"name": "howo",
...
},{
"id": 7,
"name": "alice",
....
}
]
```
`alice`'s id is 7 and `howo`'s id is 6. If you want to get a bit more in depth, I talk about it in this issue (among other things): https://gitlab.syncad.com/hive/hive/-/issues/271
Note that due to technical limitations, it's not possible to only input `to` and get all the inbound delegations, this has to be built on an L2 api (eg: HAF/hivemind/hiveSQL).
# Conclusion
I hope you found this documentation useful, if you want to check the direct RC delegation code yourself it's here: https://gitlab.syncad.com/hive/hive/-/merge_requests/245/diffs
I'll be glad to answer any questions that come up in the comments and hope to see a lot of use for rc delegations once hard fork 26 hits !
@howo
You can vote for our witness directly using Hivesigner here.