P256K

Framework

P256K

P256K is a Swift package wrapping bitcoin-core’s libsecp256k1 in a type-safe API — ECDSA, Schnorr (BIP-340), MuSig2 (BIP-327), ECDH key agreement, and key recovery — for Bitcoin, Lightning, Nostr, and other open protocols built on the secp256k1 elliptic curve.

Overview

The P256K module wraps the libsecp256k1 C codebase with a type-safe Swift API designed to match the style of Apple’s swift-crypto framework. It surfaces cryptographic primitives for the underlying Bitcoin, Lightning Network, Nostr, and other open-protocol stacks.

All operations require a secp256k1 context. The package supplies a shared P256K.Context that is created and randomized once at process startup, protecting ECDSA signatures, Schnorr signatures, and public-key generation against timing and power-analysis attacks via base-point blinding.

Where to start

Arrived from CryptoKit and wondering why P256 doesn’t work for Bitcoin or Nostr? Why CryptoKit’s P256 Can’t Sign Bitcoin or Nostr answers that question and maps each CryptoKit call to its P256K equivalent. New to P256K? Begin with Getting Started with secp256k1 in Swift for a task-oriented walkthrough of ECDSA, BIP-340 Schnorr, and ECDH key agreement. Producing ECDSA signatures for Bitcoin transactions — DER encoding, lower-S, and the SIGHASH-flagged signature element — lives in ECDSA Signing on secp256k1 for Bitcoin Transactions in Swift. Aggregating contributions from multiple parties into a single Schnorr signature? Read MuSig2 Multi-Signatures for the BIP-327 protocol. The Elliptic Curve Diffie-Hellman guide covers ECDH end-to-end — the building block behind Nostr NIP-04, Lightning’s Noise XK handshake, and BIP-352 Silent Payments. Sending Bitcoin to a reusable receiver address without on-chain linkability lives in Silent Payments. Encoding keys across formats and deriving child keys via BIP-32, Taproot, or MuSig2 tweaks both live in Working with Keys. Recovering public keys from signatures (BIP-137 / BIP-322) lives in Recovering Public Keys. Production-readiness caveats — context randomization, nonce hygiene, comparison timing, secret zeroization, signature malleability — are in Security Considerations.

Topics

Guides

Getting Started with secp256k1 in Swift
Install P256K via Swift Package Manager, trust the SharedSourcesPlugin, and produce your first verified secp256k1 signature — the entry point for Swift developers building Bitcoin, Nostr, or Lightning Network functionality.
ECDSA Signing on secp256k1 for Bitcoin Transactions in Swift
Produce ECDSA signatures on secp256k1 in Swift with P256K, encode them in DER and compact form, verify incoming signatures, and assemble the SIGHASH-flagged element Bitcoin script expects.
Elliptic Curve Diffie-Hellman
Derive a shared secret between two parties over secp256k1 using ECDH key agreement, the foundation of Nostr NIP-04 encryption, BIP-352 Silent Payments, and Lightning’s Noise XK handshake.
Silent Payments
Send Bitcoin to a reusable static address without on-chain linkability or sender–receiver interaction, using the BIP-352 Silent Payments protocol.
MuSig2 Multi-Signatures
Combine partial contributions from a fixed group of co-signers into a single Schnorr signature using the BIP-327 MuSig2 protocol.
Working with Keys
Encode P256K secp256k1 keys in raw and x-only forms, import them from PEM and DER, and derive child keys via additive or multiplicative tweaks — the foundations under Bitcoin wallet storage, Lightning interop, Nostr key handling, BIP-32 derivation, BIP-341 Taproot output construction, and BIP-327 MuSig2 aggregation.
Recovering Public Keys
Recover an ECDSA public key from a recoverable signature and its recovery ID.

Concepts

Why CryptoKit’s P256 Can’t Sign Bitcoin or Nostr
Apple’s CryptoKit and swift-crypto expose elliptic-curve primitives on NIST P-256, P-384, P-521, and Curve25519, but not secp256k1 — the curve Bitcoin, Lightning, and Nostr require. The P256K module provides the secp256k1 equivalents with a CryptoKit-shaped API.
Security Considerations
Understand the security properties of P256K and how to avoid common cryptographic pitfalls.

Essentials

ECDSA Signatures

enum Signing
secp256k1 ECDSA signing namespace providing P256K.Signing.PrivateKey for RFC 6979 deterministic signing and P256K.Signing.PublicKey for signature verification; all produced signatures are lower-S normalized.
struct PrivateKey
secp256k1 ECDSA private key for deterministically signing messages and producing P256K.Signing.ECDSASignature values using the secp256k1 curve.
struct PublicKey
secp256k1 ECDSA public key for verifying P256K.Signing.ECDSASignature values, available in compressed (33-byte) or uncompressed (65-byte) serialized form.
struct ECDSASignature
64-byte secp256k1 ECDSA signature in libsecp256k1 internal format, convertible to and from DER (variable-length, up to 72 bytes) and compact (exactly 64 bytes) representations.

Schnorr Signatures

enum Schnorr
BIP-340 Schnorr signatures over secp256k1: sign with P256K.Schnorr.PrivateKey, verify against P256K.Schnorr.XonlyKey, using a fixed 64-byte P256K.Schnorr.SchnorrSignature encoding.
struct PrivateKey
secp256k1 BIP-340 Schnorr private key for signing messages with P256K.Schnorr.SchnorrSignature and for deriving the x-only public key used in verification.
struct PublicKey
secp256k1 BIP-340 Schnorr public key in compressed or uncompressed form, from which the x-only key used for signature verification is derived via the xonly property.
struct SchnorrSignature
64-byte BIP-340 Schnorr signature over the secp256k1 elliptic curve, produced by secp256k1_schnorrsig_sign_custom and verified by secp256k1_schnorrsig_verify (both declared in Vendor/secp256k1/include/secp256k1_schnorrsig.h).
struct Nonce
A signer’s public nonce for MuSig2 operations, exchanged between signers during the nonce-aggregation phase of BIP-327.

MuSig2 Multi-Signatures

enum MuSig
MuSig2 multi-signature namespace for secp256k1 (BIP-327): aggregate signer public keys with aggregate(_:), coordinate nonce generation, collect partial signatures, and aggregate into a final 64-byte P256K.MuSig.AggregateSignature.
struct PublicKey
secp256k1 MuSig2 aggregate public key produced by aggregate(_:) via secp256k1_musig_pubkey_agg, used for partial signature verification and Taproot tweaking.
struct AggregateSignature
64-byte BIP-340 Schnorr signature produced by aggregateSignatures(_:) from all signers’ P256K.Schnorr.PartialSignature values; verifiable against the MuSig2 aggregate public key.
struct Nonce
66-byte aggregated MuSig2 public nonce produced by secp256k1_musig_nonce_agg from all signers’ individual public nonces, required before any partial signing can occur.

Key Agreement (ECDH)

enum KeyAgreement
secp256k1 ECDH (Elliptic-Curve Diffie-Hellman) key-agreement namespace providing P256K.KeyAgreement.PrivateKey and P256K.KeyAgreement.PublicKey for computing a SharedSecret via secp256k1_ecdh (declared in Vendor/secp256k1/include/secp256k1_ecdh.h).
struct PrivateKey
secp256k1 ECDH private key for deriving a SharedSecret with a peer’s P256K.KeyAgreement.PublicKey via secp256k1_ecdh.
struct PublicKey
secp256k1 ECDH public key, accepted by sharedSecretFromKeyAgreement(with:format:) to compute a SharedSecret.
struct SharedSecret
A key agreement result from which you can derive a symmetric cryptographic key.

Key Recovery

enum Recovery
secp256k1 ECDSA recoverable signature namespace: sign with P256K.Recovery.PrivateKey to produce an P256K.Recovery.ECDSASignature that allows any verifier to recover the signer’s P256K.Recovery.PublicKey without prior knowledge.
struct PrivateKey
secp256k1 ECDSA private key for producing recoverable signatures via secp256k1_ecdsa_sign_recoverable with RFC 6979 deterministic nonce generation.
struct PublicKey
secp256k1 public key recovered from an P256K.Recovery.ECDSASignature via secp256k1_ecdsa_recover, identifying the signer without prior knowledge of their public key.
struct ECDSASignature
65-byte secp256k1 ECDSA recoverable signature (64-byte compact form + 1-byte recovery ID) produced by secp256k1_ecdsa_sign_recoverable using RFC 6979 deterministic nonces.

Hashing

enum SHA256
SHA-256 hash function (RFC 6234) backed by the secp256k1_swift_sha256 shim (Sources/libsecp256k1/src/Utility.c), producing 32-byte SHA256Digest values; also provides BIP-340 tagged-hash support via taggedHash(tag:data:) using upstream secp256k1_tagged_sha256.
struct HashDigest
32-byte SHA-256 digest conforming to Digest so it can be passed directly to secp256k1 signing and verification APIs (the signature(for:) overloads on P256K.Signing.PrivateKey and P256K.Schnorr.PrivateKey that take a Digest).

Supporting Types

Protocols

protocol Digest
A type that represents the output of a hash.

Structures

struct Int256
A 256-bit signed integer backed by a UInt128 low limb and an Int128 high limb, conforming to FixedWidthInteger, BinaryInteger, and SignedInteger; the signed counterpart to UInt256.

Type Aliases

typealias CryptoKitMetaError
typealias SHA256Digest
A type alias for HashDigest used as the concrete return type of hash(data:) and taggedHash(tag:data:).

Enumerations

enum CryptoKitASN1Error
Errors from decoding ASN.1 content.

Extended Modules