# Nightfall APIs - The Nf3 class

The `Nf3` class is by far the easiest way to interact with a Nightfall node from either an Nodejs or Javascript app. The major methods in this class appear throughout this book, but a complete API description is given here as a JSDoc and some are further detailed in this chapter:

{% embed url="<https://htmlpreview.github.io/?https://raw.githubusercontent.com/EYBlockchain/nightfall_3/westlad/doc-update/doc/lib/Nf3.html>" %}

`Nf3` is a bit of a Swiss Army Knife and it contains APIs for all of the Nightfall actors.  Therefore, depending on which actor is being supported, only some of the objects methods will be needed. The most widely used ones are these:

### Object construction and initialisation

`An Nf3` object requires some asynchronous processes to run before it is fully initialised. It is an anti-pattern to put asyncs in an object's constructor and so the creating an `Nf3` object is a two step process:

#### Construction

```javascript
const nf3 = new Nf3
(
    ethereumSigningKey,
    environment = {
      clientApiUrl: 'http://localhost:8080',
      optimistApiUrl: 'http://localhost:8081',
      optimistWsUrl: 'ws://localhost:8082',
      web3WsUrl: 'ws://localhost:8546',
    },
    zkpKeys,
    clientApiAuthenticationKey,
  );
```

Where:

* `ethereumSigningKey` is a hex string containing the Ethereum signing key (private key) of the actor who will use the object.
* `environment` contains the URLs for the APIs of the various Nightfall containers that `nf3` will communicate with.  These are not necessarily all needed for every actor. For example a User will only interact with the Client container and the blockchain.  Therefore they do not need to set the Optimist URLs (although there is no harm in so doing).
* `zkpKeys` is an object of class `ZkpKeys`, containing the Users zkp keys.  These can be set later via the `setZkpKeys` method if they are not know at the point of construction and can be generated by calling the Client container's `generateZkpKeys` endpoint or, more conveniently when the `nf3` object is [initialised](#initialisation), which will both generate them from a BIP39 mnemonic and set them in the `nf3` object.
* `clientApiAuthenticationKey` this can be set if any of the nightfall containers is using an API key.  This is optional and a configurable item (see the chapter on configuring).

#### Initialisation

After construction, some async tasks need to be run to initialise the `nf3` object. Once that is done, it is ready for use.

```javascript
await nf3.init(mnemonic, contractAddressProvider);
```

Where:

* `mnemonic` is a BIP39 mnemonic, use to generate a User's zkp keys. It can be left `undefined` if the keys are already set at construction or will be set later using the `setZkpKeys` method. It is not needed for a Proposer or Challenger and can also be left `undefined` in these cases.
* `contractAddressProvider` : The `nf3` object needs find the address and ABI of Nightfall's deployed contracts, so that it interact with them. Both the Client and Optimist containers have an endpoint for this purpose. This string is used to select which of the two possibilities `nf3` should use.  Either `'client'` or `'optimist'` are acceptable values. For example, a User may have no connection to an Optimist and so would choose `'client'`. Similarly a Proposer would probably choose `'optimist'`.

### User Methods

The main methods of interest to the User are covered in the [Basic Nightfall Workflow](https://westlad.gitbook.io/nightfall_3/basic-nightfall-workflow) page.

\[ToDo add more methods]

### Proposer Methods

A Proposer must be registered with the Nightfall contracts and, as part of the registration, pay a redeemable staking fee before they can submit Layer 2 blocks to Nightfall. This is currently 20kMatic on Polygon PoS and 1MWei on Mumbai. The registration Operation also connects the Proposer to its Optimist container via a websocket. Optimist will use this websocket to send assembled blocks, embedded in `proposeBlock` transactions, to the Proposer, which it can then sign and send to the blockchain.

```javascript
await nf3.registerProposer(url, stake, fee);
```

Where:

* `url` is the URL on which the Proposer will listed for Nightfall transactions that are sent directly to it (Transfer and Withdraw; this won't work with Deposit) to avoid Gas fees.
* `stake` The amount of stake it is going to pay. This must be at least the minimum amount set for the blockchain in question (see above).  Paying more buys more time slots in which the Proposer can make blocks. Make sure there is enough in the Proposer's account to pay the stake.
* `fee` This is the amount that the Proposer charges for incorporating a transaction into a block.

After the Proposer is registered, `Nf3` can be used to start listening on its websocket for blocks to Propose:

```javascript
await nf3.startProposer();
```

This method will start listening for layer 2 blocks, and will send them to the blockchain via a `proposeBlock` function call in `State.sol`.

The above method returns an event emitter which will emit a transaction receipt event for each transaction, a rollback event for any rollbacks that occur and an error event for any errors.

### Challenger methods

There is no need to register Challengers because anyone can challenge and there is no need to stake. It's very much a case of the more the merrier. This means we can just start up a challenger and it will automatically listen for challenges coming from its Optimist, sign the challenge transactions and send them to the blockchain. Don't forget to give the Challener enough funds so that it can afford to raise challenges.

```javascript
await nf3.startChallenger();
```