docs: document ML-DSA-65 post-quantum access keys#3061
Open
r-near wants to merge 12 commits into
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Resolve access-keys.mdx: keep both the new 'Limited Access Key Caveats' (from master) and 'Signature Schemes' (this branch) sections.
…kit + near-kit-rs support - Fix hash size in access-keys.mdx and rpc/contracts.mdx: nearcore core/crypto/src/signature.rs stores a 32-byte SHA3-256 digest (ML_DSA_65_HASH_LENGTH = 32, to_public_key_handle uses Sha3_256), not a 48-byte SHA3-384 hash. - Add a Post-Quantum Keys (ML-DSA-65) section to tools/near-api.mdx with near-kit (TypeScript) and near-kit-rs (Rust) examples. - Add a tooling/library pointer from the access-keys concept page.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR documents the new ML-DSA-65 (FIPS 204) post-quantum signature scheme as a supported access-key / transaction-signing option on NEAR, alongside ed25519 and secp256k1, and explains how it appears in RPC and tooling.
Changes:
- Adds a canonical “Signature Schemes” section and an ML-DSA-65 subsection explaining on-chain hash storage and
ml-dsa-65-hash:view handles. - Documents previously missing RPC query methods (
view_access_key,view_access_key_list) and their ML-DSA-65 behavior. - Adds CLI and near-kit / near-kit-rs docs and examples for generating, adding, and using ML-DSA-65 keys; updates smart-contract anatomy docs to note ML-DSA-65 key sizes and support.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/near-api.mdx | Adds near-kit / near-kit-rs sections and examples for ML-DSA-65 key generation and transaction signing. |
| tools/cli.mdx | Documents generate-keypair, --signature-scheme ml-dsa-65, autogeneration flows, and deletion limitations for hash-only listings. |
| smart-contracts/anatomy/environment.mdx | Notes that signer_account_pk may return larger ML-DSA-65 public keys. |
| smart-contracts/anatomy/actions.mdx | Notes that add_access_key accepts ML-DSA-65 public keys without code changes. |
| protocol/accounts-contracts/access-keys.mdx | Adds signature-scheme comparison and detailed ML-DSA-65 on-chain hash/handle behavior. |
| api/rpc/contracts.mdx | Adds RPC documentation for viewing access keys and ML-DSA-65 ml-dsa-65-hash: handles in lists. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9f9a620347
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Addresses review: the snippet used `near` without defining it.
…mple Addresses review: the snippet used `near` without defining it.
Addresses review: near-sdk-rs returns a PublicKey and near-sdk-js returns raw bytes; the note implied a preformatted string.
Addresses review: 'as in the example above' was ambiguous between the full and short forms; the short form has no public-keys argument.
Addresses review: matching a view_access_key_list handle requires hashing 'near:ml-dsa-65-pubkey-hash:v1' || pubkey with SHA3-256, per nearcore MlDsa65PublicKey::to_public_key_handle; hashing the bare key won't match.
Addresses review: the limitation is that a PQ key has no implicit-account form, not that keys can only go on named accounts; an ml-dsa-65 key can be added to any existing account (named or implicit) via AddKey.
r-near
added a commit
to near/near-cli-rs
that referenced
this pull request
Jul 2, 2026
## What Adds full CLI support for the post-quantum **ML-DSA-65** (FIPS 204) signature scheme that NEAR protocol 2.13 introduces as a third access-key type, alongside the classic **Ed25519**. **1. A new offline `near generate-keypair` command** — create a key pair for either scheme and print it or save it to a JSON file (no account, no network): ``` near generate-keypair --signature-scheme ml-dsa-65 print-to-terminal near generate-keypair --signature-scheme ml-dsa-65 save-to-file ./pq-key.json ``` **2. A `--signature-scheme` option on the on-chain autogenerate flows** — `account add-key`, `account create-account fund-myself`, and `account create-account sponsor-by-faucet-service` can now autogenerate and submit an ML-DSA-65 access key: ``` near account add-key alice.testnet grant-full-access \ autogenerate-new-keypair --signature-scheme ml-dsa-65 save-to-keychain network-config testnet ... ``` The flag **defaults to `ed25519` when omitted** (and only prompts in an interactive terminal), so every existing non-interactive invocation behaves exactly as before. ML-DSA-65 keys are also emitted in the standard `ml-dsa-65:<base58>` string form, so an externally generated key can be added via the existing `account add-key … use-manually-provided-public-key` flow too. ## Why NEAR protocol **2.13** introduces post-quantum ML-DSA-65 access keys (see near/nearcore#15731). This lands the CLI side: generating PQ key pairs. Related ecosystem work: near/docs#3061, near/near-sdk-rs#1557. ##⚠️ Draft: dependency pins The nearcore 2.13 crates are **not published to crates.io yet**, so this PR temporarily git-pins every crate that exchanges `near-primitives` / `near-crypto` types to the same nearcore `2.13-release` rev (`46483c8d`) plus matching draft branches of the client libraries, so they all resolve to one version: - `near-crypto`, `near-primitives`, `near-jsonrpc-primitives`, `near-parameters` → `near/nearcore@46483c8d` (2.13-release) - `near-jsonrpc-client` → near/near-jsonrpc-client-rs#190 (draft) - `near-socialdb-client` → near/near-socialdb-client-rs#49 (draft) **These pins must be swapped back to published crates.io versions before merge/release, once nearcore 2.13 ships.** This is why the PR is a draft. ## 2.13 API adaptations Bumping to 2.13 required adapting to a few `near-primitives` / `near-crypto` changes (unrelated to keygen, but needed to compile): - New `Action::DelegateV2` / `ActionView::DelegateV2` (v2 meta-transactions) — handled in the transaction display paths. - New `ActionErrorKind::DelegateActionInvalidNonceIndex` and `InvalidAccessKeyError::DelegateActionRequiresNonGasKey` / `DelegateActionRequiresGasKey` (gas keys) — mapped to CLI error messages. - `QueryRequest::ViewState` gained `after_key` / `limit` fields. - The access-key list now returns `PublicKeyHandle`; the delete-key picker uses `full_pubkey()` and skips ML-DSA-65 entries (which are stored on-chain only as a hash, so the full key isn't recoverable for a `DeleteKey` action). - `KeyType` no longer derives `PartialEq` — comparisons switched to pattern matching. ## Scope / limitations - ML-DSA-65 keys are generated **randomly** (no seed-phrase / HD recovery — there is no NEAR standard for that yet) and have no implicit-account-id form (deferred to a later protocol milestone), so `create-account` *named*-account flows support them but the `ed25519`-only implicit-account paths are unchanged. - On-chain use of PQ keys is enabled by the `PostQuantumSignatures` protocol feature, **stabilized at protocol version 85** (the 2.13 stable version) — so the `AddKey` transactions these flows build become valid on a network once it upgrades to protocol 85 with the 2.13 rollout (it is *not* nightly-gated). ## Testing - New unit tests generate an ML-DSA-65 key pair, parse it back through `near-crypto`, and verify a signature round-trips. - Full suite green locally: `cargo test --all-features`, `cargo clippy --all-features --all-targets -- -D warnings`, `cargo fmt --check`, and the `--no-default-features` (+`ledger`) checks.
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.
What
Documents the ML-DSA-65 (FIPS 204) post-quantum signature scheme as a third access-key / transaction-signing option alongside
ed25519andsecp256k1.Covers the feature added in nearcore#15731 and its support across NEAR tooling:
Changes
protocol/accounts-contracts/access-keys.mdx— new Signature Schemes section (a canonical comparison of the three schemes) plus a Post-Quantum Keys (ML-DSA-65) subsection covering FIPS 204, key/signature sizes, on-chain hash storage (32-byte SHA3-256), theml-dsa-65-hash:view behavior, and pointers to the CLI and library tooling.api/rpc/contracts.mdx— documentsview_access_keyandview_access_key_list(previously undocumented) and howml-dsa-65keys surface asml-dsa-65-hash:in key lists.tools/cli.mdx— new Generate a key pair section (generate-keypair),--signature-scheme ml-dsa-65examples on theadd-keyautogenerate flow, and a note on thedelete-keypicker limitation for hash-only PQ keys.tools/near-api.mdx— new Post-Quantum Keys (ML-DSA-65) section withnear-kit(TypeScript) andnear-kit-rs(Rust) examples for generating, adding, and signing with a post-quantum key.smart-contracts/anatomy/actions.mdx— note thatadd_access_key/add_full_access_keyacceptml-dsa-65public keys with no code changes.smart-contracts/anatomy/environment.mdx— note thatsigner_account_pkmay return anml-dsa-65key.Notes for reviewers
PostQuantumSignaturesprotocol feature (protocol version 85, the nearcore 2.13 line) and is available on testnet, so content is written GA-style.ed25519/secp256k1. PQ keys are random-only (no seed phrase) and have no implicit-account form today (the nearcore source notes an ML-DSA-65 implicit-account form as a possible future addition).near-kit(TypeScript) andnear-kit-rs(Rust) both supportml-dsa-65end-to-end — keygen, add-key, signing, and parsing theml-dsa-65-hash:view handle.near-api-jsandpy-nearsupport is still pending, a follow-up for when it lands.ML_DSA_65_HASH_LENGTH = 32;to_public_key_handleusesSha3_256), not a 48-byte SHA3-384 hash as an earlier revision stated. Verified against nearcorecore/crypto/src/signature.rsand cross-checked against bothnear-kitandnear-kit-rs. Other values also verified: sizes 1952 / 3309 / 4032 B, domain tagnear:ml-dsa-65-pubkey-hash:v1.