Overview

Nova is a back-end service template written in Python. Most of the logic to fetch and reply to inference requests is implemented for you so you don't have to. What's left for you as a Modeler to implement is the data pre and post-processing. Depending on what your model expects, you can scale, transform, and reorder features before they are fed into the compiled model and you can do the same with the inference output before submitting it to the blockchain. Nova will automatically look for new inference requests, fetch features for a specific input in the form of a Pandas DataFrame, call your data pre-processing function, generate an inference using the compiled model you provided, call your inference post-processing function, and submit the result to the blockchain on your behalf. In the meantime, Nova also looks for inference proof requests. Once proof is requested, Nova will use the witness files saved during the inference process, your compiled model, and other EZKL supporting files to create an EZKL proof and will submit it to the blockchain.

Warning

This software is provided "as is" and without any express or implied warranties. By downloading, installing, or using this software, you agree to assume all risks associated with its use, and you agree to absolve Spectral Finance, Inc. from any liability or responsibility for any consequences resulting from the use of this software.

Please refer to the LICENSE included in this repository for the full terms.

Quick start

1. Clone this repository:

   git clone https://github.com/Spectral-Finance/nova-bootstrap.git

2. Add the dependencies you need to modeler-requirements.txt.
3. Implement your data pre and post processing
   • change the pre_process and optionally the post_process function content inside the runner.py module.
4. Build and tag a Docker image:

   docker build --platform linux/amd64 -t nova-bootstrap:latest .

5. Deploy the Docker image
   • remember to set the required environment variables before launching your container (See HERE).

Prepare ZIP file for deployment (Spectral-hosting only)

Simply run:

make zip

the command will create an upload.zip file

Compiled model and supporting files

For Nova to function properly you must provide a few additional files:

• EZKL compiled model i.e. model.ezkl: this is the result of running the ezkl.compile_circuit() function or, if you are using the CLI spectral-cli commit. You might have a compiled_model.onnx file generated by older versions of the Spectral CLI (≤ 0.1.19); this is a legacy name and can be safely renamed to model.ezkl.
• EZKL calibrated settings i.e. settings.json: this is the result of running ezkl.generate_settings() and ezkl.calibrate_settings() or the result of calling spectral-cli commit.
• EZKL proving key i.e. model_pk.pk: is needed to generate EZKL proofs and is generated as part of the spectral-cli commit command
• EZKL Structured Reference String (SRS) i.e. kzg.srs: is also needed to generate EZKL proofs and is generated as part of the spectral-cli commit command
• any other file you might need to reference to in your runner.py module e.g. Pickle files

all of the files mentioned above must be placed in the model_files folder.

Environment variables

Caution

Never commit or expose sensitive information to the public. Keep your private keys and API keys safe.

Variable	Description	Required	Default value
NOVA_SPECTRAL_API_KEY	Spectral API key. Can be retrieved HERE or by running spectral-cli show-configuration	X	N/A
NOVA_ALCHEMY_API_KEY	Alchemy App API key. Can be retrieved HERE or by running spectral-cli show-configuration	X	N/A
NOVA_CLI_WALLET_PRIVATE_KEY	Spectral CLI wallet key. Run spectral-cli show-configuration to display it	X	N/A
NOVA_MODEL_FILES_PATH	The absolute path to your model supporting files folder	X	N/A
NOVA_S3_BUCKET	required ONLY if NOVA_STORAGE_PROVIDER is set to s3	X*	N/A
NOVA_STORAGE_PROVIDER	Options are local and s3		local
NOVA_S3_PATH_PREFIX	Relative path to stored files inside an S3 bucket		""
NOVA_ARTIFACTS_PATH	Absolute path of the directory holding inference artifacts i.e. witness files for later proof generation		/tmp
NOVA_COMPILED_MODEL_PATH	EZKL compiled model absolute path.		$NOVA_MODEL_FILES_PATH/model.ezkl
NOVA_SETTINGS_PATH	EZKL settings file absolute path		$NOVA_MODEL_FILES_PATH/settings.json
NOVA_PROVING_KEY_PATH	EZKL proving key absolute path		$NOVA_MODEL_FILES_PATH/model_pk.pk
NOVA_SRS_PATH	EZKL SRS path		$NOVA_MODEL_FILES_PATH/kzg.srs
NOVA_LOG_LEVEL	Logging level. Options are DEBUG, INFO, WARNING, ERROR and CRITICAL		INFO
NOVA_INFERENCE_SUBMISSION_ENABLED	Enables submission of inferences to the smart contract		True
NOVA_PROOF_SUBMISSION_ENABLED	Enables submission of proofs to the smart contract		True
NOVA_POLLING_ENABLED	Enables continuous polling for new inference and proof requests		True
NOVA_INFERENCE_POLLING_INTERVAL	Interval of time in seconds between queries for new inference requests		20
NOVA_PROOF_POLLING_INTERVAL	Interval of time in seconds between queries for new proof requests		3600
NOVA_PULSE_HOST	Base URL of the Pulse service		https://subscription-library.spectral.finance
NOVA_PLUMBER_HOST	Base URL of the Plumber service		https://plumber.spectral.finance
NOVA_ALCHEMY_HOST	Base URL of the Alchemy service		https://arb-mainnet.g.alchemy.com
NOVA_CHALLENGE_ADDRESS	Challenge smart contract address		0xFDC1BE05aD924e6Fc4Ab2c6443279fF7C0AB5544
NOVA_TX_EXPLORER_URL	URL of the Arbiscan explorer		https://arbiscan.io/tx
NOVA_GAS_PRICE_GWEI	Pre-set gas price		0.12
NOVA_GAS	Pre-set gas amount for writing operations		4000000
NOVA_CHAIN_ID	Arbitrum One chain ID		42161

*required only if NOVA_STORAGE_PROVIDER is set to s3

Local deployment with Docker Compose

To build and start the Nova container simply run:

docker compose up --build

or to run it as a daemon:

docker compose up --build -d

Push a Docker image to Amazon ECR (Elastic Container Registry)

Tag the Docker image:

docker tag nova-bootstrap:latest <your_ecr_repository_uri>/nova-bootstrap:latest

Push the image to ECR:

aws ecr get-login-password --region <your_aws_region> | docker login --username AWS --password-stdin <your_ecr_repository_uri>
docker push <your_ecr_repository_uri>/nova-bootstrap:latest

Deploy on Amazon EKS (Elastic Kubernetes Service)

Update the Kubernetes deployment YAML file (deployment.yaml) to use the correct image and configuration.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nova-bootstrap-deployment
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: nova-bootstrap
    spec:
      containers:
      - name: nova-bootstrap-container
        image: <your_ecr_repository_uri>/nova-bootstrap:latest

Apply the deployment:

kubectl apply -f deployment.yaml

Cleanup (Optional)

If needed, clean up the resources.

kubectl delete deployment nova-bootstrap-deployment