algorand-falcon

Python bindings for the Algorand deterministic Falcon (det1024) post-quantum signature scheme, built directly over the algorand/falcon C implementation with cffi in API mode.

  • Deterministic: the same (private key, message) always produces a byte-identical signature (no nonce). This is what Algorand consensus requires.
  • Bit-exact: compiled with the emulated floating-point, no-SIMD configuration, so signatures are identical across compilers and CPU architectures. This is locked in by the upstream known-answer tests (KATs).
  • Small surface: generate, sign, verify. The C-mirroring layer is private, so there is no low-level API to misuse. See ADR 0006.
  • Typed: ships py.typed, and the public surface is fully annotated.
  • abi3 wheels: one wheel per platform works on CPython 3.10+.

Installation

pip install algorand-falcon

Prebuilt cp310-abi3 wheels are published for Linux (x86_64/aarch64, manylinux and musllinux), macOS (x86_64/arm64), and Windows (amd64). The only runtime dependency is cffi.

Quickstart

from algorand_falcon import falcon1024, InvalidSignature

signer = falcon1024.Signer.generate()  # or generate(seed) for deterministic keygen

signature = signer.sign(b"hello world")  # deterministic, compressed format

verifier = signer.verifying_key()
verifier.verify(b"hello world", signature)  # returns None; raises on failure
assert verifier.is_valid(b"hello world", signature)

try:
    verifier.verify(b"tampered", signature)
except InvalidSignature:
    print("rejected")

Using with py-algorand-sdk

py-algorand-sdk has no Falcon dependency: its post-quantum signer takes a public key plus a callback that signs exact preimage bytes. signer.sign is that callback.

from algosdk import mnemonic, constants
from algosdk.signer import Falcon1024TransactionSigner
from algorand_falcon import falcon1024

seed = mnemonic.to_pq_seed(my_mnemonic, constants.falcon_1024_scheme)  # 32 bytes
signer = falcon1024.Signer.generate(seed)

txn_signer = Falcon1024TransactionSigner(signer.public_key, signer.sign)

The same signer serves both preimage families the SDK produces: transactions ("TX" + msgpack) and delegated logic signatures ("PQProgram" + address + program).

API

The parameter set lives in the falcon1024 namespace module; the exceptions are shared at the top level. The scheme is det1024 (deterministic Falcon-1024), and its signatures are not interoperable with standard randomized ("salted") Falcon-1024.

falcon1024.Signer

  • falcon1024.Signer.generate(seed: bytes | None = None) -> Signer: create a new keypair. seed=None derives from a fresh 48-byte OS CSPRNG seed. Otherwise seed deterministically derives the keypair and may be any non-empty length. For Algorand accounts it is the 32 bytes algosdk.mnemonic.to_pq_seed() returns.
  • falcon1024.Signer(private_key: bytes): load from stored private key bytes. The public key is recomputed from the private key, so the two can never disagree.
  • .sign(message: bytes) -> bytes: deterministic compressed signature.
  • .verifying_key() -> falcon1024.Verifier
  • .private_key, .public_key: raw bytes.

falcon1024.Verifier

  • falcon1024.Verifier(public_key: bytes)
  • .verify(message, signature) -> None: raises InvalidSignature on failure.
  • .is_valid(message, signature) -> bool
  • .public_key

Key hygiene

sign and verify operate on raw bytes with no domain separation: the message is signed verbatim. A key that signs arbitrary caller-supplied bytes can be made to sign a valid transaction preimage, so use one key for one protocol. To reproduce a signature an application made over a structured object, sign the digest that application hashes to, not the object itself.

Constants

falcon1024.PUBLIC_KEY_SIZE=1793, falcon1024.PRIVATE_KEY_SIZE=2305, falcon1024.COMPRESSED_SIG_MAX_SIZE=1423. Resolved from the C header macros at build time, so they can never drift from the vendored library.

Exceptions

FalconError is the base class. InvalidSignature, KeygenError, and SigningError derive from it. Wrong key sizes raise the built-in ValueError (signatures are variable-length, so a malformed one fails verification with InvalidSignature instead), and arguments of the wrong type raise TypeError.

Development

Requires uv. The Falcon C sources are vendored as a git submodule.

git clone --recurse-submodules https://github.com/algorandfoundation/falcon-py
cd falcon-det1024
uv sync                 # builds the cffi extension + installs dev deps
uvx pre-commit install  # ruff format + lint on every commit
uv run pytest           # roundtrip, determinism, tamper, surface, and 512+32 KATs
uv run mypy             # strict
uv run ruff format . && uv run ruff check --fix .   # or let the pre-commit hook do it

Wheels are built with cibuildwheel (uvx cibuildwheel locally). Releases are cut by python-semantic-release from conventional commits.

See docs/adr/ for the key decisions and docs/DESIGN.md for the binding and packaging reference.

License

MIT. See LICENSE. Bundles the Falcon C implementation (Copyright (c) 2017-2020 Falcon Project, MIT).

Project links

Data verified by PyPI on Aug 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for algorand-foundation from gravatar.com algorand-foundation

Credits

Author: Algorand Foundation

GitHub Statistics

Data verified by PyPI on Aug 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

falcon post-quantum signature cryptography algorand det1024

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

algorand_falcon-0.1.0.tar.gz (183.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

algorand_falcon-0.1.0-cp310-abi3-win_amd64.whl (78.2 kB view details)

Uploaded CPython 3.10+Windows x86-64

algorand_falcon-0.1.0-cp310-abi3-win32.whl (75.3 kB view details)

Uploaded CPython 3.10+Windows x86

algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl (340.9 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl (310.7 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl (343.9 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.26+ x86-64manylinux: glibc 2.28+ x86-64

algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (319.2 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

algorand_falcon-0.1.0-cp310-abi3-macosx_11_0_arm64.whl (100.2 kB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

algorand_falcon-0.1.0-cp310-abi3-macosx_10_9_x86_64.whl (109.5 kB view details)

Uploaded CPython 3.10+macOS 10.9+ x86-64

File details

Details for the file algorand_falcon-0.1.0.tar.gz.

File metadata

  • Download URL: algorand_falcon-0.1.0.tar.gz
  • Upload date:
  • Size: 183.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for algorand_falcon-0.1.0.tar.gz
Algorithm Hash digest
SHA256 f09a43c240a6182436b6878b552ba55d4e62f4a61512c0f899039379d65551f6
MD5 3b1f8f4c7eacd2256ddf990b52dbeb78
BLAKE2b-256 86546f2116607309602a4fc081c78cb0087ea109b09665070bb280d4e4f886b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0.tar.gz:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 eb440d73eca868e4a1f06d274690bf7f2f6d9d2b4cae14ee2d1ef3ee3871164e
MD5 aad46d8cea6784309cbd86e4d66e474a
BLAKE2b-256 0f32ee852631ecf8e7e4ef4825054977bda45dbafe46dea450f450c454207959

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-win32.whl.

File metadata

  • Download URL: algorand_falcon-0.1.0-cp310-abi3-win32.whl
  • Upload date:
  • Size: 75.3 kB
  • Tags: CPython 3.10+, Windows x86
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-win32.whl
Algorithm Hash digest
SHA256 6be23ea214c6609c6670b6c1af7b7040f2db7741adee1caddb8b83ee45d96e30
MD5 289e19c2afdc684faecfd5f677bc5eb0
BLAKE2b-256 95a8885f9b630868be1731b1a5d43d47f189415ac7f849a6132716323e562d3e

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-win32.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 afe3b55ad7b040f4bd9f50ebfe84f36135eac72dfc213b53b25e83bcea3d65c3
MD5 fb526cc8f8c1f0a71d2fd2217cafcd84
BLAKE2b-256 18557fcf1da6cbd6f308df11c8d0b2339c4ab3ec22b32f709b17876d1161d75b

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 844d814e8206a4237074a25b05b99848a6fb8bc9adf9699383ebfe4bf6e260c2
MD5 accfa4fb48cb2cd3c2abfe58a80dc944
BLAKE2b-256 c6a24124b7304808cd3f16cac9b4960ae38dfebf445bb8ed6f0108e71b92866c

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8365a0a54b653649f94c6e080d20b00ef8d1dca20f2b128dc787ae1535bc58ac
MD5 b2313addfd7dcb6a985ba3f4ea6ea050
BLAKE2b-256 92d3799db6fceedd9956d8d10f9b650adea43e47a0e1c750535a597d141f46f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 02b5c1743b5e1f00aa2837c0749ed48503a336ca21cf33470d30c94872694ca7
MD5 64fa9c2b16d6f016c109e39c333b4dcf
BLAKE2b-256 1e6677e1710daffca63397f4cf5d8ecec7a250a8a6c0dea63b582a1166963080

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3421fab415e7cb3349327644c06dd489bf974516b3f7549d87d455faf1398ffe
MD5 fdf3cca410ff3003dff8479e1fb1f5c1
BLAKE2b-256 e11cbbc170908f4cb65c00a04e57fed210fc3242808e0e5c6044d2c41a750d6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file algorand_falcon-0.1.0-cp310-abi3-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for algorand_falcon-0.1.0-cp310-abi3-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 2d24a49a250883efca44bdb97b16804c2282eed9ffc951d77eab5dc002ec270b
MD5 0bce24103b356229be6de71f6f2aa1d6
BLAKE2b-256 ecf44aead6fd851ec226556a5610e35c8f7a2a16ad4a97888544c187169b14af

See more details on using hashes here.

Provenance

The following attestation bundles were made for algorand_falcon-0.1.0-cp310-abi3-macosx_10_9_x86_64.whl:

Publisher: release.yml on algorandfoundation/falcon-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page