secp256k1.cr

Build Status Documentation Release Language License

a native library implementing secp256k1 purely for the crystal language. secp256k1 is the elliptic curve used in the public-private-key cryptography required by bitcoin and ethereum.

this library allows for key generation of:

this library allows for address generation of:

furthermore, this library allows for:

installation

add the secp256k1 library to your shard.yml

dependencies:
  secp256k1:
    github: q9f/secp256k1.cr
    version: "~> 0.3"

usage

tl;dr, check out crystal run ./try.cr!

# import secp256k1
require "secp256k1"

this library exposes the following modules (in logical order):

basic usage:

# generates a new keypair
key = Secp256k1::Keypair.new
# => #<Secp256k1::Keypair:0x7f8be5611d80>

# gets the private key
key.get_secret
# => "53d77137b39427a35d8c4b187f532d3912e1e7135985e730633e1e3c1b87ce97"

# gets the compressed public key with prefix
compressed = Secp256k1::Util.public_key_compressed_prefix key.public_key
# => "03e097fc69f0b92f711620511c07fefdd648e469df46b1e4385a00a1786f6bc55b"

generate a compressed bitcoin mainnet address:

# generates a new keypair
key = Secp256k1::Keypair.new
# => #<Secp256k1::Keypair:0x7f8be5611d80>

# generates a compressed bitcoin account from the keypair
btc = Secp256k1::Bitcoin::Account.new key, "00", true
# => #<Secp256k1::Bitcoin::Account:0x7f81ef21ab80>

# gets the wallet-import format (checksummed private key)
btc.wif
# => "Kz2grUzxEAxNopiREbNpVbjoitAGQVXnUZY4n8pNdmWdVqub99qu"

# gets the compressed bitcoin addresss
btc.address
# => "1Q1zbmPZtS2chwxpviqz6qHgoM8UUuviGN"

generate a checksummed ethereum address:

# generates a new keypair
key = Secp256k1::Keypair.new
# => #<Secp256k1::Keypair:0x7f81ef21ad00>

# generates an ethereum account from the keypair
eth = Secp256k1::Ethereum::Account.new key
# => #<Secp256k1::Ethereum::Account:0x7f81ef1faac0>

# gets the private key
eth.get_secret
# => "53d77137b39427a35d8c4b187f532d3912e1e7135985e730633e1e3c1b87ce97"

# gets the ethereum addresss
eth.address
# => "0x224008a0F3d3cB989c807F568c7f99Bf451328A6"

documentation

the full library documentation can be found here: q9f.github.io/secp256k1.cr

generate a local copy with:

crystal docs

testing

the library is entirely specified through tests in ./spec; run:

crystal spec --verbose

understand

private keys are just scalars and public keys are points with x and y coordinates.

bitcoin public keys can be uncompressed #{p}#{x}#{y} or compressed #{p}#{x}. both come with a prefix p which is useless for uncompressed keys but necessary for compressed keys to recover the y coordinate on the secp256k1 elliptic curve.

ethereum public keys are uncompressed #{x}#{y} without any prefix. the last 20 bytes slice of the y coordinate is actually used as address without any checksum. a checksum was later added in eip-55 using a keccak256 hash and indicating character capitalization.

neither bitcoin nor ethereum allow for recovering public keys from an address unless there exists a transaction with a valid signature on the blockchain.

known issues

note: this library should not be used in production without proper auditing.

found another issue? report it: github.com/q9f/secp256k1.cr/issues

contribute

create a pull request, and make sure tests and linter passes.

this pure crystal implementation is based on the python implementation wobine/blackboard101 which is also used as reference to write tests against. it's a complete rewrite of the abandoned packetzero/bitcoinutils for educational purposes.

honerable mention for the bitcoin wiki and the ethereum stackexchange for providing so many in-depth resources that supported this project in reimplementing everything.

license: apache license v2.0

contributors: @q9f