# Secp256k1

Utility functions for [secp256k1](https://www.secg.org/sec2-v2.pdf) ECDSA cryptography.

:::info
The `Secp256k1` module is a friendly wrapper over [`@noble/curves/secp256k1`](https://github.com/paulmillr/noble-curves), an **audited** implementation of [secp256k1](https://www.secg.org/sec2-v2.pdf)
:::

## Examples

Below are some examples demonstrating common usages of the `Secp256k1` module:

* [Computing a Random Private Key](#computing-a-random-private-key)

* [Getting a Public Key](#getting-a-public-key)

* [Signing a Payload](#signing-a-payload)

* [Verifying a Signature](#verifying-a-signature)

### Computing a Random Private Key

A random private key can be computed using [`Secp256k1.randomPrivateKey`](/api/Secp256k1/randomPrivateKey):

```ts twoslash
import { Secp256k1 } from 'ox'

const privateKey = Secp256k1.randomPrivateKey()
// @log: '0x...'
```

### Getting a Public Key

A public key can be derived from a private key using [`Secp256k1.getPublicKey`](/api/Secp256k1/getPublicKey):

```ts twoslash
import { Secp256k1 } from 'ox'

const privateKey = Secp256k1.randomPrivateKey()

const publicKey = Secp256k1.getPublicKey({ privateKey }) // [!code focus]
// @log: { x: 3251...5152n, y: 1251...5152n }
```

### Signing a Payload

A payload can be signed using [`Secp256k1.sign`](/api/Secp256k1/sign):

```ts twoslash
import { Secp256k1 } from 'ox'

const privateKey = Secp256k1.randomPrivateKey()

const signature = Secp256k1.sign({
  payload: '0xdeadbeef',
  privateKey
}) // [!code focus]
// @log: { r: 1251...5152n, s: 1251...5152n, yParity: 1 }
```

### Verifying a Signature

A signature can be verified using [`Secp256k1.verify`](/api/Secp256k1/verify):

```ts twoslash
import { Secp256k1 } from 'ox'

const privateKey = Secp256k1.randomPrivateKey()
const publicKey = Secp256k1.getPublicKey({ privateKey })
const signature = Secp256k1.sign({
  payload: '0xdeadbeef',
  privateKey
})

const isValid = Secp256k1.verify({
  // [!code focus]
  payload: '0xdeadbeef', // [!code focus]
  publicKey, // [!code focus]
  signature // [!code focus]
}) // [!code focus]
// @log: true
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Secp256k1.createKeyPair`](/api/Secp256k1/createKeyPair) | Creates a new secp256k1 ECDSA key pair consisting of a private key and its corresponding public key. |
| [`Secp256k1.getPublicKey`](/api/Secp256k1/getPublicKey) | Computes the secp256k1 ECDSA public key from a provided private key. |
| [`Secp256k1.getSharedSecret`](/api/Secp256k1/getSharedSecret) | Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key. |
| [`Secp256k1.randomPrivateKey`](/api/Secp256k1/randomPrivateKey) | Generates a random ECDSA private key on the secp256k1 curve. |
| [`Secp256k1.recoverAddress`](/api/Secp256k1/recoverAddress) | Recovers the signing address from the signed payload and signature. |
| [`Secp256k1.recoverPublicKey`](/api/Secp256k1/recoverPublicKey) | Recovers the signing public key from the signed payload and signature. |
| [`Secp256k1.sign`](/api/Secp256k1/sign) | Signs the payload with the provided private key. |
| [`Secp256k1.verify`](/api/Secp256k1/verify) | Verifies a payload was signed by the provided address. |