Acki Nacki VM Instructions Business-Level Specification

Prepared by Pruvendo

Purpose

The purpose of the present document is to create business-level specification (highest-level of specification) for the Acki Nacki - specific VM instructions. This document is intended to:

  • Be thoroughly reviewed by the Customer

  • Act as a base for the high-level specification

Introduction

Being a TVM-based blockchain, Acki Nacki follows its specification and instruction set. However, some additional instructions are required to support some specific features introduced in Acki Nacki. Such instructions are described in the present document.

Acki Nacki - specific instructions

For all the instructions below the current account is taken from c4 register.

CNVRTSHELLQ

Signature : C727 n()n ( - ) , where 0n<22560 \leq n < 2^{256}

Brief description: Transforms SHELL into the same amount of VMSHELL (using 1:1 ratio)

Input : nmod264n \bmod 2^{64} - amount of nanotokens to exchange

Behavior:

  • If the sender has enough balance of SHELL, the required amount of SHELL’s are transformed into VMSHELL

  • Otherwise, the whole balance of SHELL is transformed into VMSHELL

  • In any case the counter of special operations is increased

MINTECC

Signature : C726 y x()y \space x ( - ), where 0x<2560 \leq x < 256, 0y<21280 \leq y < 2^{128}

Brief description : mints the required amount of any ECC tokens, can be called by a special contract only

Input : xx - index of ECC token, yy - amount of nanotokens to mint

Behavior:

  • If the contract is not special, NOT_SPECIAL_CONTRACT error happens

  • If the adding of tokens fails, OVERFLOW error happens

  • Otherwise:

    • token balance is increased by the specified amount

    • counter of special actions is increased

MINTSHELL

Signature : C728 n()n ( - ), where 0n<21280 \leq n < 2^{128}

Brief description : mints SHELL tokens, up to the specified amount, using the available credit

Input : n - amount of SHELL nanotokens to be minted

Behavior:

  • In case of infinite credit, the specified amount of SHELL tokens is minted

  • Up to the nn tokens will be minted, but Minted shell value afterwards does not exceed available credit

  • Minted shell value is increased by the amount of the minted value

  • In case of success the counter of special actions is increased

All the values must not exceed 21282^{128}.

CALCBKREWARD

Signature : C729 r s τ e Σ n a (ρ)r \space s \space \tau \space e \space \varSigma \space n \space a \space (\rho), where:

  • 0r<21280 \leq r < 2^{128}

  • 0s<21280 \leq s < 2^{128}

  • 0τ<21280 \leq \tau < 2^{128}

  • 0e<21280 \leq e < 2^{128}

  • 0Σ<21280 \leq \varSigma < 2^{128}

  • 0n<21280 \leq n < 2^{128}

  • 0a<21280 \leq a < 2^{128}

Brief description : calculates and returns validator’s reward by the end of each epoch

Input :

  • rr - reputation coefficient

  • ss - stake

  • τ\tau - total stake at the epoch start

  • ee - epoch duration

  • 𝛴- total amount of minted reward tokens

  • nn - number of active block keepers

  • aa - last calculated reward adjustment

Output : ρ\rho - assigned reward

Behavior: it follows Acki Nacki tokenomics:

  • Σ=0ρ=aer109n\varSigma = 0 \rArr \rho = \frac{aer}{10^9n}

  • 0<Σ<TOTALSUPPLYρ=aers109τ0\lt\varSigma \lt TOTALSUPPLY \Rightarrow \rho = \frac{a e r s}{10^9 \tau}

  • ΣTOTALSUPPLYρ=0\varSigma \ge TOTALSUPPLY \Rightarrow \rho =0

CALCMINSTAKE

Signature : C730 v n t s (μ)v \space n \space t \space s \space (\mu), where:

  • 0v<21280 \leq v < 2^{128}

  • 0n<21280 \leq n < 2^{128}

  • 0t<21280 \leq t < 2^{128}

  • 0s<21280 \leq s < 2^{128}

Brief description : calculates a minimal deposit for a validator (in nanotokens)

Input:

  • vv - number of needed active blokkeepers (10000)

  • nn - number of active blokkeepers

  • tt - network duration + ⅓ of the preepoch duration

  • ss - total reward amount subtracted by the total slashed amount

Output : μ\mu - minimally allowed stake

Behavior: it follows Acki Nacki tokenomics

CALCBKREWARDADJ

Signature: C733 t a p r s (𝛼)t \space a \space p \space r \space s \space (𝛼)

All the values must not exceed 21282 ^ {128}.

Brief description: adjusts reward engine to be aligned with the theoretical curve.

Input:

  • tt - network time

  • aa - the previous adjustment factor

  • pp - reward period

  • rr- average reputation coefficient

  • ss - total reward amount

Output : aa - new adjustment factor

Behavior: it follows Acki Nacki tokenomics

CALCREPCOEF

Signature: C734 r(c)r (c)

All the values must not exceed 21282^{128}

Brief description: calculates reputation coefficient based on the reputation time.

Input:

  • rr - reputation time

Output : cc - reputation coefficient

Behavior: it follows Acki Nacki tokenomics

Zero-knowledge instructions

One of the common drawbacks of common blockchain systems is a necessity to use seed phrases for authentication. It’s hard to remember them and other (off-chain) approaches such as OAuth2 that commonly are better in terms or user experience than the former one. The popular solution is to use self-custodial wallets such as Metamask or TON Wallet. Such wallets are often not so transparent as desired and can be vulnerable to attacks (such as the recent Atomic Wallet case).

The provided solution is intended to support popular off-chain authentication systems in blockchain, thus preventing frequent authentication using seed phrases or off-chain wallets, thus combining a high level of security with great user experience.

The solution is based on Zero-knowledge technology and follows the similar solution implemented in Sui blockchain named zkLogin and described here in details, with some important exceptions:

  1. Salt is not defined by the user, but simply works as a second password

  2. Poseidon is used as a hash function

  3. The Ceremony process is completely new

The changes are to be described in a separate document.

VERGRTH16

Verifies the proofs using Groth16 algorithm

Signature : C731 π ρ i (b)\pi \space \rho \space i \space (b), where:

  • ρTvmSlice\rho \isin TvmSlice

  • dTvmSliced \isin TvmSlice

  • 0i<2320 \leq i < 2^{32}

  • bBb \isin B

Brief description : checks zk-Snark proof, returning the logical result

Input:

  • π\pi - slice is public inputs

  • ρ\rho - proof (in terms of zk-Snark)

  • ii - algorithm used, where:

    • 0 - unsecure algorithm

    • 1 - secure algorithm

    • anything else - test algorithm

Output:

  • bb - boolean value that indicates if the verification was correct or not

Behavior is as follows:

  1. π\pi and ρ\rho are decoded into corresponding arrays of bytes

  2. proofs then decoded into array of Proof<Bn254> structures, using external function

  3. public inputs, in their turn, are decoded into array of Fr (where Fr={0,...,22561}Fr = \lbrace 0, ..., 2^{256} -1 \rbrace) using: a. external methods for deserialization to the array of FieldElementWrapper b. wrapping by the first element

  4. Depending on ii, selected the predefined set of verifying keys - unsecure, secure or test

  5. External function with data calculated at steps 2-4 is called to verify the proofs using Groth16 algorithm

POSEIDON

Calculates Poseidon hash.

Signature : C732 i m p μ s h z (π)i \space m \space p \space \mu \space s \space h \space z \space (\pi), where:

  • 0i<2560 \leq i < 256

  • 0m<2640 \leq m < 2^{64}

  • 0p<22560 \leq p < 2^{256}

  • μTvmSlice\mu \isin TvmSlice

  • sTvmSlices \isin TvmSlice

  • hTvmSliceh \isin TvmSlice

  • zTvmSlicez \isin TvmSlice

  • πTvmCell\pi \isin TvmCell

Input:

  • hh - JWT header (base64)

  • ss - iss (provider’s name) (base64)

  • μ\mu - modulus

  • pp - ephemeral public key

  • mm - maximum epoch

  • ii - key index

Output:

  • π\pi - array of public input as a cell

Behavior:

  1. Initially:

    1. zz is transformed into a string (z-string)

    2. hh is transformed into a base64 string (h-string)

    3. ss is transformed into a base64 string (s-string)

    4. μ\mu is transformed into array of bytes (𝜇-array)

    5. pp is transformed into a byte array with proper number of bytes, extra bytes are dropped, in case of lack of bytes exception must be raised

    6. mm is transformed into u64 (m64)

    7. ii is transformed into a base64 string (i-string)

  2. Then:

    1. zstringz-string is transformed into big number using an external function

    2. hstringh-string is transformed into big number using an external function

    3. sstrings-string is transformed into big number using an external function

    4. μarray\mu -array is transformed into big number using an external function

    5. pstringp-string is split into two big numbers using external function

    6. m64m64 is transformed into a string and then, to big number using an external function

    7. istringi-string is transformed into big number using an external function

  3. Then, an array of public inputs is created using a call of external functions

  4. Finally, the list is serialized into a cell and push into a stack

Last updated