rbsecp256k1 6.0.1 → 6.0.2

data/documentation/index.md

@@ -1,378 +1,391 @@
-rbsecp256k1 Reference
-=====================
-
-Find your topic in the index, or refer to one of the examples below.
-
-Classes and Modules
--------------------
-
-| Module                     | Classes                                          | Utilities
-|----------------------------|:-------------------------------------------------|:--------------------------------
-| [Secp256k1](secp256k1.md)  | [Context](context.md)                            | [Util](util.md)
-|                            | [KeyPair](key_pair.md)                           |
-|                            | [PublicKey](public_key.md)                       |
-|                            | [XOnlyPublicKey](xonly_public_key.md)            |
-|                            | [PrivateKey](private_key.md)                     |
-|                            | [SharedSecret](shared_secret.md)                 |
-|                            | [Signature](signature.md)                        |
-|                            | [RecoverableSignature](recoverable_signature.md) |
-|                            | [SchnorrSignature](schnorr_signature.md)         |
-
-Glossary
---------
-
-**[Context](context.md)** is a libsecp256k1 library context. It contains
-pre-computed tables and values to make ECDSA signing and verification more
-efficient.
-
-**[KeyPair](key_pair.md)** is a Secp256k1 elliptic-curve key pair.
-
-**[PublicKey](public_key.md)** is a Secp256k1 public key. It can come in either
-compressed or uncompressed format.
-
-**[XOnlyPublicKey](xonly_public_key.md)** is a Secp256k1 x-only public key.
-
-**[PrivateKey](private_key.md)** is a 64-byte Secp256k1 private key.
-
-**[SharedSecret](shared_secret.md)** A 32-byte shared secret computed from a
-public key (point) and private key (scalar).
-
-**[Signature](signature.md)** is an ECDSA signature of the SHA-256 message hash
-of a piece of data.
-
-**[RecoverableSignature](recoverable_signature.md)** is a recoverable ECDSA signature of the SHA-256 message
-hash of a piece of data.
-
-**[SchnorrSignature](schnorr_signature.md)** is a Schnorr signature of a 32-byte message.
-
-Examples
---------
-
-### 1. Creating a libsecp256k1 context
-
-This example demonstrates how to create a new libsecp256k1 context. This is the
-first step of using this library:
-
-```ruby
-context = Secp256k1::Context.create
-# => #<Secp256k1::Context:0x0000559b0bd8f5d0>
-```
-
-### 2. Generating a key pair
-
-This example shows how to generate a new public-private key pair:
-
-```ruby
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-# => #<Secp256k1::KeyPair:0x0000559b0bc876b0>
-```
-
-### 3. Getting compressed and uncompressed public key representations
-
-This example shows how to generate compressed and uncompressed public keys:
-
-```ruby
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-# 1. Get the binary representation of compressed public key
-key_pair.public_key.compressed
-# => "\x03D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE"
-
-# 2. Show hex representation of compressed public key
-Secp256k1::Util.bin_to_hex(key_pair.public_key.compressed)
-# => "034488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe"
-
-# 3. Get the binary representation of uncompressed public key
-key_pair.public_key.uncompressed
-# => "\x04D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE XRew\x1F\e\x05\xC8\xDC\xA7\xE3\x8C\xBD\x91s?\xFCW\xD5\xB3\xA8aaCCG\xD4\x94m\xA5c"
-
-# 4. Show hex representation of uncompressed public key
-Secp256k1::Util.bin_to_hex(key_pair.public_key.uncompressed)
-# => "044488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe20585265771f1b05c8dca7e38cbd91733ffc57d5b3a86161434347d4946da563"
-```
-
-### 3. Signing a message
-
-This example shows how to sign a message using your private key:
-
-```ruby
-require 'digest'
-
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
-# => #<Secp256k1::Signature:0x0000559b0bc79358>
-```
-
-### 4. Getting DER and Compact signature encodings
-
-This example shows you how to get the DER encoded and compact encoded
-representations of a signature:
-
-```ruby
-require 'digest'
-
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
-
-# 1. Get the compact binary representation
-signature.compact
-# => "\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC\x00"
-
-# 2. Get the compact hex representation
-Secp256k1::Util.bin_to_hex(signature.compact)
-# => "ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a089134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc00"
-
-# 3. Get the DER binary representation
-signature.der_encoded
-# => "0E\x02!\x00\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x02 \x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC"
-
-# 4. Get the DER hex representation
-Secp256k1::Util.bin_to_hex(signature.der_encoded)
-# => "3045022100ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a0890220134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc"
-```
-
-### 5. Verifying a signature
-
-This example shows how to verify a signature using a public key:
-
-```ruby
-require 'digest'
-
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-hash = Digest::SHA256.digest("test message")
-
-signature = context.sign(key_pair.private_key, hash)
-
-# 1. Verify signature against matching message
-context.verify(signature, key_pair.public_key, hash)
-# => true
-
-# 2. Verify signature against different message
-context.verify(signature, key_pair.public_key, hash)
-# => false
-```
-
-### 6. Loading a private key or key pair from private key data
-
-This example shows how to load a key pair from raw binary private key data:
-
-```ruby
-context = Secp256k1::Context.create
-
-#1. Load private key alone
-private_key = Secp256k1::PrivateKey.from_data("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
-# => #<Secp256k1::PrivateKey:0x00005647df1bcd30>
-
-# 2. Load key pair from private key data
-key_pair = context.key_pair_from_private_key("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
-# => #<Secp256k1::KeyPair:0x0000559b0bbf9a90>
-```
-
-### 7. Loading a public key from binary data
-
-This example shows how to load a public key from binary data:
-
-```ruby
-# 1. Load public key from uncompressed pubkey
-public_key = Secp256k1::PublicKey.from_data("\x04$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5\xEEEj\xAB\xD9\xFE\b\e7Zk\xC5{k\x12\xE3\xEA\xA2\xA5\xD7\xC1\xA5&\xE5|:K\xA9 X\xA3\x90")
-# => #<Secp256k1::PublicKey:0x0000559b0bdc72f0>
-
-# 2. Load public key from compressed pubkey
-public_key = Secp256k1::PublicKey.from_data("\x02$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5")
-# => #<Secp256k1::PublicKey:0x0000559b0bdd3668>
-```
-
-### 8. Loading a DER or compact encoded signature
-
-This example shows how to load signatures from binary data:
-
-```ruby
-# 1. From DER encoded signature
-signature = Secp256k1::Signature.from_der_encoded("0D\x02 <\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\x02 \t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f")
-# => #<Secp256k1::Signature:0x0000559b0b823d58>
-
-# 2. From compact signature
-signature = Secp256k1::Signature.from_compact("<\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f\x00")
-# => #<Secp256k1::Signature:0x0000559b0bdcaa68>
-```
-
-Schnorr Signature Examples
---------------------------
-
-### 1. Checking for the Schnorr module
-
-To check if you have compiled the schnorr signature module into your local
-libsecp256k1 run the following:
-
-```ruby
-Secp256k1.have_schnorr?
-# => true
-```
-
-### 2. Calculate the tagged SHA-256 hash of data
-
-You can produce the tagged SHA-256 hash recommended for use with Schnorr
-signatures as follows:
-
-```ruby
-context = Secp256k1::Context.create
-
-context.tagged_sha256('my_test_tag', 'data')
-=> "0\x85|\xC8h\x9A\x8C^\x0FoD\xDF\xD0,\x1C\x1EV}\xE8\xA8<\xC5\xA5vI\x9E`=\x9B\xC4\xA8\xAE"
-```
-
-### 3. Sign and verify a message using Schnorr signatures
-
-```ruby
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-message = context.tagged_sha256('my_test_tag', 'data')
-
-schnorr_sig = context.sign_schnorr(key_pair, message)
-=> #<Secp256k1::SchnorrSignature:0x00007f4de11e5768>
-
-schnorr_sig.verify(message, key_pair.xonly_public_key)
-=> true
-
-schnorr_sig.serialized
-=> "\x16\xEF\x04\xB0JP\xE9\x90\xC2\xB1\xE6-l\xDB\x1D\xAE\xAAc\xBF@9s\x02\xC2\xD5[\xFB\x19Q\xFAI^Hj\xD1)\xBE\xEA\xA5!a\xAD\xBEO\xCE7\x9Em\x13;\xE8R\x8A\x81$\nv\xF4\xD3\xB25\xA9\xF9\xC0"
-```
-
-### 4. Load a Schnorr signature from binary serialized version
-
-```ruby
-context = Secp256k1::Context.create
-
-schnorr_sig_raw = "\x16\xEF\x04\xB0JP\xE9\x90\xC2\xB1\xE6-l\xDB\x1D\xAE\xAAc\xBF@9s\x02\xC2\xD5[\xFB\x19Q\xFAI^Hj\xD1)\xBE\xEA\xA5!a\xAD\xBEO\xCE7\x9Em\x13;\xE8R\x8A\x81$\nv\xF4\xD3\xB25\xA9\xF9\xC0"
-
-Secp256k1::SchnorrSignature.from_data(schnorr_sig_raw)
-=> #<Secp256k1::SchnorrSignature:0x00007f4de1225818>
-```
-
-Recoverable Signature Examples
-------------------------------
-
-### 1. Checking for recovery module
-
-To check if you have compiled the recovery module into your local libsecp256k1
-run the following:
-
-```ruby
-Secp256k1.have_recovery?
-# => true
-```
-
-### 2. Sign data producing recoverable signature
-
-You can sign data producing a recoverable signature as follows:
-
-```ruby
-yrequire 'digest'
-
-hash = Digest::SHA256.digest('test message')
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-signature = context.sign_recoverable(key_pair.private_key, hash)
-# => #<Secp256k1::RecoverableSignature:0x000055f2ea76e548>
-```
-
-### 3. Serialize recoverable signature as compact representation
-
-You can produce the compact binary serialization of a recoverable signature:
-
-```ruby
-require 'digest'
-
-hash = Digest::SHA256.digest('test message')
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-signature = context.sign_recoverable(key_pair.private_key, hash)
-compact_data, recovery_id = signature.compact
-# => ["D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D", 1]
-```
-
-### 4. Recoverable signature from compact representation
-
-You can load a recoverable signature give its compact representation and
-recovery ID:
-
-```ruby
-context = Secp256k1::Context.create
-
-compact_data = "D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D"
-recovery_id = 1
-
-signature = context.recoverable_signature_from_compact(compact_data, recovery_id)
-# => #<Secp256k1::RecoverableSignature:0x000055f2ea7615c8>
-```
-
-### 5. Convert recoverable signature to non-recoverable signature
-
-You can convert a recoverable signature to a non-recoverable signature suitable
-for use by all methods that take a [Signature](signature.md) object:
-
-```ruby
-require 'digest'
-
-hash = Digest::SHA256.digest('test message')
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
-signature = recoverable_signature.to_signature
-# => #<Secp256k1::Signature:0x000055f2ea8ca4f0>
-```
-
-### 6. Recover public key from recoverable signature
-
-You can recover the [PublicKey](public_key.md) associated with a recoverable signature:
-
-```ruby
-require 'digest'
-
-hash = Digest::SHA256.digest('test message')
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
-public_key = recoverable_signature.recover_public_key(hash)
-# => #<Secp256k1::PublicKey:0x000055f2ea756678>
-
-public_key == key_pair.public_key
-# => true
-```
-
-EC Diffie-Hellman
------------------
-
-### 1. Checking for ECDH module
-
-To check if you have compiled the ECDH module into your local libsecp256k1 run
-the following:
-
-```ruby
-Secp256k1.have_ecdh?
-# => true
-```
-
-### 2. Generating a shared secret
-
-To generate a shared secret run the following:
-
-```ruby
-context = Secp256k1::Context.create
-key_pair = context.generate_key_pair
-
-shared_secret = context.ecdh(key_pair.public_key, key_pair.private_key)
-shared_secret.data
-# => "\x1FQ\x90X\xA5\xF2\xAEx;\xD7i\xB6\\T,2[\x90\xD1)a$\x1CA\x17\x8F\e\x91\xE3\x06C\x93"
-```
+rbsecp256k1 Reference
+=====================
+
+Find your topic in the index, or refer to one of the examples below.
+
+Classes and Modules
+-------------------
+
+| Module                     | Classes                                          | Utilities
+|----------------------------|:-------------------------------------------------|:--------------------------------
+| [Secp256k1](secp256k1.md)  | [Context](context.md)                            | [Util](util.md)
+|                            | [KeyPair](key_pair.md)                           |
+|                            | [PublicKey](public_key.md)                       |
+|                            | [XOnlyPublicKey](xonly_public_key.md)            |
+|                            | [PrivateKey](private_key.md)                     |
+|                            | [SharedSecret](shared_secret.md)                 |
+|                            | [Signature](signature.md)                        |
+|                            | [RecoverableSignature](recoverable_signature.md) |
+|                            | [SchnorrSignature](schnorr_signature.md)         |
+
+Glossary
+--------
+
+**[Context](context.md)** is a libsecp256k1 library context. It contains
+pre-computed tables and values to make ECDSA signing and verification more
+efficient.
+
+**[KeyPair](key_pair.md)** is a Secp256k1 elliptic-curve key pair.
+
+**[PublicKey](public_key.md)** is a Secp256k1 public key. It can come in either
+compressed or uncompressed format.
+
+**[XOnlyPublicKey](xonly_public_key.md)** is a Secp256k1 x-only public key.
+
+**[PrivateKey](private_key.md)** is a 64-byte Secp256k1 private key.
+
+**[SharedSecret](shared_secret.md)** A 32-byte shared secret computed from a
+public key (point) and private key (scalar).
+
+**[Signature](signature.md)** is an ECDSA signature of the SHA-256 message hash
+of a piece of data.
+
+**[RecoverableSignature](recoverable_signature.md)** is a recoverable ECDSA signature of the SHA-256 message
+hash of a piece of data.
+
+**[SchnorrSignature](schnorr_signature.md)** is a 64-byte Schnorr signature of a message of any byte length.
+
+Examples
+--------
+
+### 1. Creating a libsecp256k1 context
+
+This example demonstrates how to create a new libsecp256k1 context. This is the
+first step of using this library:
+
+```ruby
+context = Secp256k1::Context.create
+# => #<Secp256k1::Context:0x0000559b0bd8f5d0>
+```
+
+### 2. Generating a key pair
+
+This example shows how to generate a new public-private key pair:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+# => #<Secp256k1::KeyPair:0x0000559b0bc876b0>
+```
+
+### 3. Getting compressed and uncompressed public key representations
+
+This example shows how to generate compressed and uncompressed public keys:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+# 1. Get the binary representation of compressed public key
+key_pair.public_key.compressed
+# => "\x03D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE"
+
+# 2. Show hex representation of compressed public key
+Secp256k1::Util.bin_to_hex(key_pair.public_key.compressed)
+# => "034488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe"
+
+# 3. Get the binary representation of uncompressed public key
+key_pair.public_key.uncompressed
+# => "\x04D\x88\xD6 3|3\x836\xCB(\x9CW%\xF4T\xB7\xCD\x8AF T\xE7\xE8\xCE\xB0\xC7c{\xE2:\xFE XRew\x1F\e\x05\xC8\xDC\xA7\xE3\x8C\xBD\x91s?\xFCW\xD5\xB3\xA8aaCCG\xD4\x94m\xA5c"
+
+# 4. Show hex representation of uncompressed public key
+Secp256k1::Util.bin_to_hex(key_pair.public_key.uncompressed)
+# => "044488d620337c338336cb289c5725f454b7cd8a462054e7e8ceb0c7637be23afe20585265771f1b05c8dca7e38cbd91733ffc57d5b3a86161434347d4946da563"
+```
+
+### 3. Signing a message
+
+This example shows how to sign a message using your private key:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
+# => #<Secp256k1::Signature:0x0000559b0bc79358>
+```
+
+### 4. Getting DER and Compact signature encodings
+
+This example shows you how to get the DER encoded and compact encoded
+representations of a signature:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign(key_pair.private_key, Digest::SHA256.digest("test message"))
+
+# 1. Get the compact binary representation
+signature.compact
+# => "\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC\x00"
+
+# 2. Get the compact hex representation
+Secp256k1::Util.bin_to_hex(signature.compact)
+# => "ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a089134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc00"
+
+# 3. Get the DER binary representation
+signature.der_encoded
+# => "0E\x02!\x00\xAB#e6_\x866\e\xAC\e\x92W\xC8a\x84N\xD4\xB6\x88\xF8\xEE\xDF\xFBC\xE8j\xB2\xF0\x10\xB8\xA0\x89\x02 \x13L\e\x9E\x91cB\xD7\xAC\x11\xF7\x02,Y&TM\xA5zp\xFD\xB3\xB1\xDCIV\xBB\\\xAF\x16@\xFC"
+
+# 4. Get the DER hex representation
+Secp256k1::Util.bin_to_hex(signature.der_encoded)
+# => "3045022100ab2365365f86361bac1b9257c861844ed4b688f8eedffb43e86ab2f010b8a0890220134c1b9e916342d7ac11f7022c5926544da57a70fdb3b1dc4956bb5caf1640fc"
+```
+
+### 5. Verifying a signature
+
+This example shows how to verify a signature using a public key:
+
+```ruby
+require 'digest'
+
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+hash = Digest::SHA256.digest("test message")
+
+signature = context.sign(key_pair.private_key, hash)
+
+# 1. Verify signature against matching message
+context.verify(signature, key_pair.public_key, hash)
+# => true
+
+# 2. Verify signature against different message
+context.verify(signature, key_pair.public_key, hash)
+# => false
+```
+
+### 6. Loading a private key or key pair from private key data
+
+This example shows how to load a key pair from raw binary private key data:
+
+```ruby
+context = Secp256k1::Context.create
+
+#1. Load private key alone
+private_key = Secp256k1::PrivateKey.from_data("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
+# => #<Secp256k1::PrivateKey:0x00005647df1bcd30>
+
+# 2. Load key pair from private key data
+key_pair = context.key_pair_from_private_key("I\nX\x85\xAEz}\n\x9B\xA4\\\x81)\xD4\x9Aq\xFDH\t\xBE\x8EP\xC5.\xC6\x1F7-\x86\xA0\xCB\xF9")
+# => #<Secp256k1::KeyPair:0x0000559b0bbf9a90>
+```
+
+### 7. Loading a public key from binary data
+
+This example shows how to load a public key from binary data:
+
+```ruby
+# 1. Load public key from uncompressed pubkey
+public_key = Secp256k1::PublicKey.from_data("\x04$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5\xEEEj\xAB\xD9\xFE\b\e7Zk\xC5{k\x12\xE3\xEA\xA2\xA5\xD7\xC1\xA5&\xE5|:K\xA9 X\xA3\x90")
+# => #<Secp256k1::PublicKey:0x0000559b0bdc72f0>
+
+# 2. Load public key from compressed pubkey
+public_key = Secp256k1::PublicKey.from_data("\x02$\xA2\xE7\xBB1\xC4|tN\xE6\xE4J-\xED\x9A[\xAFf-<\x14\x84^QQ\"\x14\xC3\x91\xE4\xF2\xB5")
+# => #<Secp256k1::PublicKey:0x0000559b0bdd3668>
+```
+
+### 8. Loading a DER or compact encoded signature
+
+This example shows how to load signatures from binary data:
+
+```ruby
+# 1. From DER encoded signature
+signature = Secp256k1::Signature.from_der_encoded("0D\x02 <\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\x02 \t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f")
+# => #<Secp256k1::Signature:0x0000559b0b823d58>
+
+# 2. From compact signature
+signature = Secp256k1::Signature.from_compact("<\xC6\x7F/\x921l\x89Z\xFBs\x89p\xEE\x18u\x8B\x92\x9D\xA6\x84\xC5Y<t\xB7\xF1\f\xEE\f\x81J\t\"\xDF]\x1D\xA7W@^\xAAokH\b\x00\xE2L\xCF\x82\xA3\x05\x1E\x00\xF9\xFC\xB19\x0F\x93|\xB1f\x00")
+# => #<Secp256k1::Signature:0x0000559b0bdcaa68>
+```
+
+Schnorr Signature Examples
+--------------------------
+
+### 1. Checking for the Schnorr module
+
+To check if you have compiled the schnorr signature module into your local
+libsecp256k1 run the following:
+
+```ruby
+Secp256k1.have_schnorr?
+# => true
+```
+
+### 2. Calculate the tagged SHA-256 hash of data
+
+You can produce the tagged SHA-256 hash recommended for use with Schnorr
+signatures as follows:
+
+```ruby
+context = Secp256k1::Context.create
+
+context.tagged_sha256('my_test_tag', 'data')
+=> "0\x85|\xC8h\x9A\x8C^\x0FoD\xDF\xD0,\x1C\x1EV}\xE8\xA8<\xC5\xA5vI\x9E`=\x9B\xC4\xA8\xAE"
+```
+
+### 3. Sign and verify a message using Schnorr signatures
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+message = context.tagged_sha256('my_test_tag', 'data')
+
+schnorr_sig = context.sign_schnorr(key_pair, message)
+=> #<Secp256k1::SchnorrSignature:0x00007f4de11e5768>
+
+schnorr_sig.verify(message, key_pair.xonly_public_key)
+=> true
+
+schnorr_sig.serialized
+=> "\x16\xEF\x04\xB0JP\xE9\x90\xC2\xB1\xE6-l\xDB\x1D\xAE\xAAc\xBF@9s\x02\xC2\xD5[\xFB\x19Q\xFAI^Hj\xD1)\xBE\xEA\xA5!a\xAD\xBEO\xCE7\x9Em\x13;\xE8R\x8A\x81$\nv\xF4\xD3\xB25\xA9\xF9\xC0"
+```
+
+Messages can also be signed directly, including empty strings. No implicit
+hashing, padding, or truncation is performed; use the same bytes for verification.
+The tagged hash above is an explicit application choice.
+
+```ruby
+message = 'a message of any byte length'.b
+signature = context.sign_schnorr(key_pair, message)
+signature.verify(message, key_pair.xonly_public_key)
+# => true
+signature.serialized.bytesize
+# => 64
+```
+
+### 4. Load a Schnorr signature from binary serialized version
+
+```ruby
+context = Secp256k1::Context.create
+
+schnorr_sig_raw = "\x16\xEF\x04\xB0JP\xE9\x90\xC2\xB1\xE6-l\xDB\x1D\xAE\xAAc\xBF@9s\x02\xC2\xD5[\xFB\x19Q\xFAI^Hj\xD1)\xBE\xEA\xA5!a\xAD\xBEO\xCE7\x9Em\x13;\xE8R\x8A\x81$\nv\xF4\xD3\xB25\xA9\xF9\xC0"
+
+Secp256k1::SchnorrSignature.from_data(schnorr_sig_raw)
+=> #<Secp256k1::SchnorrSignature:0x00007f4de1225818>
+```
+
+Recoverable Signature Examples
+------------------------------
+
+### 1. Checking for recovery module
+
+To check if you have compiled the recovery module into your local libsecp256k1
+run the following:
+
+```ruby
+Secp256k1.have_recovery?
+# => true
+```
+
+### 2. Sign data producing recoverable signature
+
+You can sign data producing a recoverable signature as follows:
+
+```ruby
+yrequire 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign_recoverable(key_pair.private_key, hash)
+# => #<Secp256k1::RecoverableSignature:0x000055f2ea76e548>
+```
+
+### 3. Serialize recoverable signature as compact representation
+
+You can produce the compact binary serialization of a recoverable signature:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+signature = context.sign_recoverable(key_pair.private_key, hash)
+compact_data, recovery_id = signature.compact
+# => ["D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D", 1]
+```
+
+### 4. Recoverable signature from compact representation
+
+You can load a recoverable signature give its compact representation and
+recovery ID:
+
+```ruby
+context = Secp256k1::Context.create
+
+compact_data = "D,\x9C\xA6%I\x14-\xCA\xC0\x11\x0F\xEB\x1E\xB0\xB6\\-\xE2\b\x98\xFB\xEA\xD5\x9BZ\xE6\xDF#\xC1\x1A\xEEL\xF02\xB1\xE9{\r\xEBhh<\\\xCF\xB6\x98\xEA\x8F\xF65\xF2\xBF\x84\xD8\xE5x\xF0\xA5)\xA2Wb\x9D"
+recovery_id = 1
+
+signature = context.recoverable_signature_from_compact(compact_data, recovery_id)
+# => #<Secp256k1::RecoverableSignature:0x000055f2ea7615c8>
+```
+
+### 5. Convert recoverable signature to non-recoverable signature
+
+You can convert a recoverable signature to a non-recoverable signature suitable
+for use by all methods that take a [Signature](signature.md) object:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
+signature = recoverable_signature.to_signature
+# => #<Secp256k1::Signature:0x000055f2ea8ca4f0>
+```
+
+### 6. Recover public key from recoverable signature
+
+You can recover the [PublicKey](public_key.md) associated with a recoverable signature:
+
+```ruby
+require 'digest'
+
+hash = Digest::SHA256.digest('test message')
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+recoverable_signature = context.sign_recoverable(key_pair.private_key, hash)
+public_key = recoverable_signature.recover_public_key(hash)
+# => #<Secp256k1::PublicKey:0x000055f2ea756678>
+
+public_key == key_pair.public_key
+# => true
+```
+
+EC Diffie-Hellman
+-----------------
+
+### 1. Checking for ECDH module
+
+To check if you have compiled the ECDH module into your local libsecp256k1 run
+the following:
+
+```ruby
+Secp256k1.have_ecdh?
+# => true
+```
+
+### 2. Generating a shared secret
+
+To generate a shared secret run the following:
+
+```ruby
+context = Secp256k1::Context.create
+key_pair = context.generate_key_pair
+
+shared_secret = context.ecdh(key_pair.public_key, key_pair.private_key)
+shared_secret.data
+# => "\x1FQ\x90X\xA5\xF2\xAEx;\xD7i\xB6\\T,2[\x90\xD1)a$\x1CA\x17\x8F\e\x91\xE3\x06C\x93"
+```