# @zilliqa-js/crypto
> Cryptographic abstractions for working with Zilliqa's crypto primitives

## Functions

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

Safely generates bytes using [`Window.crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Window/crypto) in the browser or the built-in `crypto` in node.

**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` - 20-byte hex-encoded address.


### `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**

```
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**

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

**Interfaces**

```
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;
}
```
