# @zilliqa-js/crypto

> Cryptographic abstractions for working with Zilliqa's crypto primitives

## Functions

### `randomBytes(bytes: number): string`

Safely generates random bytes.

#### Parameters

`bytes`: `number` - the number of bytes to randomly generate

#### Returns

`string` - n randomly-generated bytes (hex-encoded).

### `generatePrivateKey(): string`

Generates a cryptographically-secure 32-byte private key.

#### Parameters

None

#### Returns

`string` - 32-byte hex-encoded private key.

### `getPubKeyFromPrivateKey(privateKey: string): string`

Retrieves the public key of the given hex-encoded private key.

#### Parameters

`privateKey`: `string` - 32-byte hex-encoded private key.

#### Returns

`string` - 33-byte hex-encoded public key.

### `getAddressFromPrivateKey(privateKey: string): string`

Retrieves the address from the given hex-encoded private key.

#### Parameters

`privateKey`: `string` - 32-byte hex-encoded private key.

#### Returns

`string` - 20-byte hex-encoded address.

### `compressPublicKey(publicKey: string): string`

Compresses a full-length public key by using a sign byte (02 or 03).

#### Parameters

`publicKey`: `string` - 65-byte hex-encoded public key.

#### Returns

`string` - 32-byte hex-encoded public key.

### `getAddressFromPublicKey(publicKey: string): string`

Returns the address derived from the given publicKey.

#### Parameters

`publicKey`: `string` - 32-byte hex-encoded compressed public key.

#### Returns

`string` - 20-byte hex-encoded address.

### `verifyPrivateKey(privateKey: string): boolean`

Returns true if the given privateKey is valid.

#### Parameters

`string` - 32-byte hex-encoded private key.

#### Returns

`boolean`

### `sign(msg: Buffer, privateKey: string, pubKey: string): string`

Generates a Schnorr signature over a `Buffer` of arbitrary bytes. This function
must be used to sign all transactions to be broadcast on the blockchain.

#### Parameters

`msg`: `Buffer` - arbitrary sequence of bytes to be signed. `privateKey`:
`string` - 32-byte hex-encoded private key. `pubKey`: `string` - 32-byte
hex-encoded private key.

#### Returns

`boolean`

### `encryptPrivateKey(kdf: KDF, privateKey: string, passphrase: string): Promise<string>`

Generates a version 3 keystore file that complies with the
[Web3 Secret Storage definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition).

#### Parameters

`kdf`: `'pbkdf2' | 'scrypt'` - the key derivation function. Only `pbkdf2` and
`scrypt` are currently supported. `privateKey`: `string` - 32-byte hex-encoded
private key. `passphrase`: `string` - the passphrase to be used to encrypt the
private key.

#### Returns

`Promise<string>` - the stringified JSON file.

### `decryptPrivateKey(passphrase: string, keystore: KeystoreV3): Promise<string>`

Generates a version 3 keystore file that complies with the
[Web3 Secret Storage definition](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition).

#### Parameters

`passphrase`: `string` - the passphrase to be used to encrypt the private key.
`keystore`: `KeystoreV3` - the object containing the deserialised JSON obtained
from `encryptPrivateKey`.

#### Returns

`Promise<string>` - the hex-encoded private key.

### `toBech32Address(address: string): string`

Encodes a 20-byte hex encoded address as a bech32 address. Non-hex-encoded
strings will cause an error to be thrown.

#### Parameters

`address`: `string` - the 20-byte hex-encoded address. `0x` prefix optional.

#### Returns

`string` - the bech32 encoded address. It is always prefixed by `zil1`, where
`1` is a separator.

#### Example

```text
0x1d19918a737306218b5cbb3241fcdcbd998c3a72 (hex) -> zil1r5verznnwvrzrz6uhveyrlxuhkvccwnju4aehf (bech32)
```

### `fromBech32Address(address: string): string`

Encodes a a bech32 address as a hex-encoded string. Invalid bech32 addresses
will cause an error to be thrown.

#### Parameters

`address`: `string` - the 42-character bech32 address.

#### Returns

`string` - the checksum 20-byte hex-encoded address.

#### Example

```test
zil1r5verznnwvrzrz6uhveyrlxuhkvccwnju4aehf (bech32) -> 0x1d19918a737306218b5cbb3241fcdcbd998c3a72 (hex)
```

#### Interfaces

```ts
interface PBKDF2Params {
  salt: string;
  dklen: number;
  c: number;
}

interface ScryptParams {
  salt: string;
  dklen: number;
  n: number;
  r: number;
  p: number;
}

type KDFParams = PBKDF2Params | ScryptParams;

interface KeystoreV3 {
  address: string;
  crypto: {
    cipher: string;
    cipherparams: {
      iv: string;
    };
    ciphertext: string;
    kdf: KDF;
    kdfparams: KDFParams;
    mac: string;
  };
  id: string;
  version: 3;
}
```