docs: simplify the email signature guide - #86
Merged
Conversation
The signature required for API authorization is a standard Ed25519 signature over the BLAKE2b-256 hash of the email address, so state the formula plainly and lead with examples that need no blockchain SDK. Add a test vector so an implementation can be checked before it is pointed at the API. The previous JavaScript example printed the signature of the unhashed email address, which is not what the endpoint verifies. Also document two things that were missing: the Profile screen shows the private key concatenated with the public key, and the Authorization key pair is the one to sign with. Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
Cre-eD
force-pushed
the
docs/simplify-email-signature-guide
branch
from
August 17, 2026 19:00
073b931 to
cf6f043
Compare
The pinned third-party action ships Vercel CLI 25.1.0, and the deploy endpoint now rejects anything older than 47.2.2, so every branch push failed. Call the CLI directly at a current release instead, and move the job off the end-of-life Node 18 runtime. Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
The Vercel project is still set to Node 18, which the platform has discontinued, so the build fails before it starts. Declare the version in the manifest, where it takes precedence over the project setting. Signed-off-by: Dmitrii Creed <creeed22@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
New API users get stuck on the
signaturefield of the authorization request. The signing tutorial presented it as an SDK-specific operation, and its JavaScript example printed the signature of the unhashed email address, so anyone comparing their own output against the documented one concludes their implementation is broken.What changed
Signing user email addresses rewritten:
signature = Hex( Ed25519-Sign( authPrivateKey, BLAKE2b-256( UTF-8(email) ) ) ).422: signing with the Blockchain key pair instead of the Authorization one, and passing a 128-character private key.Authorizing an account: notes that
signatureandauthPublicKeyHexmust come from the same Authorization key pair.Web App UI: notes that a 128-character private key on the Profile screen is the private key followed by the public key, and that only the first 64 characters are the private key.
Calling API endpoints: points users who only need to upload, flag or download data at the Web App, which requires no code.
Verification
pnpm docs:build,pnpm format:checkandpnpm lintpass locally.57e711...e630a, matching the test vector and the documented output.