Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify full shard key v.s. full shard id #579

ninjaahhh opened this issue Jun 18, 2019 · 1 comment


None yet
1 participant
Copy link

commented Jun 18, 2019

we have those two phrases everywhere in documentation and code and they somehow are used interchangeably. here we should clarify things up and see what's the best way to represent their differences


in one word, full shard ID is the normalized version of a full shard key.

e.g. given chain ID 0x1 of the shard size 4, the shard with ID 0x2 gives us the unique full shard ID 0x00010006 (0x1 << 16 + 4 + 2). it's a normalized ID because there are many more full shard keys that can map to this specific full shard ID, because

<full shard ID> = <full shard key> & 0xffff0000 + <shard size> + <full shard key> & (shard size - 1)

thus following full shard keys will map to the same full shard ID: 0x0001ff02, 0x0001aaae, 0x00011236, and of course 0x00010006 (the normalized full shard ID itself), etc. all requiring the last 2 bits to be "10" (aka shard ID 0x2).


we accept full shard key from outside world, then normalize to full shard ID and locate to the correct shard for handling address operations, while storing full shard keys into the address (though ideally we probably should store full shard IDs instead of keys). also all those transactions refer to full shard keys instead of full shard IDs.

therefore, we should design APIs that take full shard keys as inputs, but output full shard IDs as outputs all the time. one exception is probably for transactions, where full shard keys represent the user initiated behavior, while we return fullShardId to denote which shard processes and return fromFullShardKey and toFullShardKey to represent user inputs.


This comment has been minimized.

Copy link
Contributor Author

commented Jun 20, 2019

@ninjaahhh ninjaahhh closed this Jun 20, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.