@pivotswap/pivot-utilities

Provides common utilities that are used by Pivot packages

Documentation

DKG and Pivot Adapters

This repository presents two essential classes: DKGAdapter and PivotAdapter. Specifically tailored to interact with the Pivot Protocol, they serve as robust tools for computational tasks and the generation of input proofs for ZK circuits.

DKGAdapter

The DKGAdapter class is responsible for generating inputs required for zero-knowledge proofs (ZK Proofs) during the Distributed Key Generation (DKG) process.

Methods

constructor(T_COMMITTEE: number, N_COMMITTEE: number)

Initializes the DKGAdapter instance with the provided parameters.

• Parameters:
  • T_COMMITTEE: Threshold number of committee members.
  • N_COMMITTEE: Total number of committee members.

round1RCommit(): Promise<TRound1Commit>

Performs round 1 commitment contribute, including coefficient calculation and generating the commitment data.

• Returns: A promise that resolves to an object containing the coefficients and commitments for dkg round 1.
• Throws: An error if round 1 commit data generation fails.

round2Commit(index: number, coef: bigint[], commitmentsOfIndex: TBabyJubPoint[], colCommitment0: TBabyJubPoint[]): Promise<TRound2ZK>

Performs round 2 commitment contribute. After this step, each private key (SK) of committee member can be calculated if the committee member has all the data from other committee members.

• Parameters:
  • index: The index of the current committee member.
  • coef: The coefficients generated in round 1.
  • commitmentsOfIndex: Commitment of the current index committee.
  • colCommitment0: First column of commitment matrix.
• Returns: A promise that resolves to the circuit input data for zero-knowledge proof of dkg round 2.
• Throws: An error if round 2 commit data generation fails.

revealCommit(index: number, coef: bigint[], pkAddressIn: TBabyJubPoint, commitmentsOfIndex: TBabyJubPoint[], colCommitment0: TBabyJubPoint[], allEncrypteds: bigint[][]): Promise<TRevealZK>

Performs the reveal transaction request for the current committee member.

• Parameters:
  • index: The index of the current committee member.
  • coef: The coefficients generated in round 1.
  • pkAddressIn: Public address generated from deposit nullifier, emmited in the deposit transaction.
  • commitmentsOfIndex: Commitment of the current index.
  • colCommitment0: First column of commitment matrix.
  • allEncrypteds: All encrypted data. That is, the encrypted data of all committee members in round 2.
• Returns: A promise that resolves to the circuit input data for zero-knowledge proof of reveal transaction request.
• Throws: An error if reveal commit data generation fails.

caculateLeads(ds: TBabyJubPoint[], requestersIndex: bigint[]): Promise<bigint[]>

Calculates the leads to be used in tracking the transaction.

• Parameters:
  • ds: Array of public keys (shared points) computed using the private key (SK) of each committee member with PkAddressIn.
  • requestersIndex: Array of requesters' indices in dkg.
• Returns: A promise that resolves to the calculated leads.
• Throws: An error if an error occurs during the calculation of leads.

PivotAdapter

The PivotAdapter class supports generating parameters for deposit and zero-knowledge proof (ZK Proof) parameters for withdraw, and swap operations in Pivot Protocol.

Methods

constructor(PKCOMMITEE: TBabyJubPoint)

Initializes the PivotAdapter instance with the provided public key of the DKG.

• Parameters:
  • PKCOMMITEE: The public key of the DKG.

generateNullifier(): Promise<bigint>

Generates a random private nullifier. Nullifier is a unique value that is one piece of the private data when a user deposits.

• Returns: A promise that resolves to the generated nullifier.
• Throws: An error if an error occurs during nullifier generation.

deposit(nullifier: bigint, v: bigint[]): Promise<TDeposit>

Generates parameters for a deposit operation.

• Parameters:
  • nullifier: The private nullifier for the deposit. This is first private data of the user.
  • v: The private array of values to deposit. This is the second private data of the user.
• Returns: A promise that resolves to the deposit parameters.
• Throws: An error if an error occurs during deposit parameter calculation.

withdraw(nullifier: bigint, recipient: string, relayer: string, v: bigint[], indexAmount: bigint, feePercent: bigint, tree: TTree): Promise<TWithdrawZK>

Generates parameters for the ZKP input data for a withdrawal operation.

• Parameters:
  • nullifier: The private nullifier, which is the first private data of the user.
  • recipient: The recipient address.
  • relayer: The relayer address.
  • v: The private array, which is the second private data of the user.
  • indexAmount: The index of element in the private array, value of this index will be withdrawn.
  • feePercent: The fee percentage for the withdraw.
  • tree: The Merkle tree state based on the leaf - the commitment of the deposit operation.
• Returns: A promise that resolves to the withdrawal parameters for ZK proof.
• Throws: An error if an error occurs during withdrawal parameter calculation.

swap(nullifier: bigint, recipient: string, relayer: string, v: bigint[], indexAmount: bigint, feePercent: bigint, tokenOut: string, amountOutMin: bigint, tree: TTree): Promise<TSwapZK>

Generates parameters for the ZKP input data for a swap operation.

• Parameters:
  • nullifier: The nullifier, which is the first private data of the user.
  • recipient: The recipient address.
  • relayer: The relayer address.
  • v: The private array, which is the second private data of the user.
  • indexAmount: The index of element in the private array, value of this index will be swapped.
  • feePercent: The fee percentage for the swap.
  • tokenOut: The token to be received after the swap.
  • amountOutMin: The minimum amount of tokenOut expected from the swap.
  • tree: The Merkle tree state based on the leaf - the commitment of the deposit operation.
• Returns: A promise that resolves to the swap parameters for ZK proof.
• Throws: An error if an error occurs during swap parameter calculation.

Usage

To use these classes, you can instantiate them with the required parameters and call the methods as needed for your DKG or ZK proof operations.

Example

import { DKGAdapter } from './DKGAdapter';
import { PivotAdapter } from './PivotAdapter';

==========================
|| Initialize DKGAdapter ||
==========================
const dkgAdapter = new DKGAdapter(3, 5);

// commitee index of the commitee in DKG.
export const commiteeIndex: number = 1;

// generate from round1RCommit function. This is private data of the commitee
export const commiteeCoef: bigint[] = [
  1521219607456538479560352247364080770839529194387209257305110509519427164770n,
  1056632955158706126972199835983209006657926273636263157749582109458568790917n,
  2577738990442352208929058457585112838043586353795449596491382213820122857334n,
];

// commitment of current index commitee. Get from smart contract
export const commitmentsOfIndex: TBabyJubPoint[] = [
  [
    14035499958838649786785293212491846909881677271918553780651836461764448182033n,
    1937161267065790866895193370855896596764303301706160961304870810538684452193n,
  ],
  [
    14844718663624989471383110674274312782617363758245870244157555276947299241851n,
    17230270276507673813710153822440231043954586153384949974437372181226744274304n,
  ],
  [
    18962175409618358931006115709125196114740546894681412336616366144038536716301n,
    19576791005981178245728710474285104417812846192080742190029862881883129038670n,
  ],
];

// get commitment matrix from smart contract and get the first column
export const colCommitment0: TBabyJubPoint[] = [
  [
    14035499958838649786785293212491846909881677271918553780651836461764448182033n,
    1937161267065790866895193370855896596764303301706160961304870810538684452193n,
  ],
  [
    2573432035470088658250777143124641458270186292399272349481986917575647042257n,
    8496540773152362513909987640773408831857182792600981299952781192078644211422n,
  ],
  [
    8409500570894888957850289847419968860374414039119946899642922359523409216154n,
    347234036263891571582793893706093621454140389621544763614086832277250817645n,
  ],
  [
    19455721581263576490408430999609317063708919485786506633666610157316173873412n,
    8776061468928582401774997688451988048007900813488161683226545631906164647561n,
  ],
  [
    9089851110583707726004096242499150243146320010081621449843185942627672066202n,
    13492303095002506423104967460447405581167571949052720485599045876219823067120n,
  ],
];


// emit from deposit transaction was executed.
export const pkAddress: TBabyJubPoint = [
  11504656306667765137504037971796461430914255895455958202365368149753066664983n,
  9604695707863003473345644549569384556017439611893764141909045059476297154194n,
];

// all encrypted data of the commitee. This data is get from smart contract after round 2 commit success.
export const allEncrypteds: bigint[][] = [
  [
    0n,
    17386198263134900117182102590989279315706661435428435918078009202993660585726n,
    19132404654905760962867322291912817737730681402313027320433857824287159315434n,
    5103277361747813328709833750551639069422062469285949186364190240838094707048n,
    7878400404334040820021961190697098815715646559002006398333782044846883542809n,
  ],
  [
    16742691388564270385240965767124307106372122646574233445424777454083325168334n,
    0n,
    6148031646734866863673776528020495609187296995032469965936398273955933058478n,
    20153357740536532986334153658780286679634350832721572045109243523250465003346n,
    7518047715016950547909523980309698608493752249094990480896407596281731107572n,
  ],
  [
    21004038074162893763907161936653808812334389298641078178079696774629367249376n,
    5866726389124093215032026608221225472908617702615598004234363315706717276800n,
    0n,
    13313806417249414299950737173125875816333469025365054265523032431489292968016n,
    3823824051658401486197853100138482168132362083535798080169280634462996320990n,
  ],
  [
    4854172687776992060782994893378148801101455542767267759724873250085899493100n,
    20579639844996673255854558062136339796287707692448185195047605273557877579110n,
    13974246803189785062344286919267239335439013840930528571462841490043662200738n,
    0n,
    17155221653958712180653806021992359591556037340961119118648346174919117098287n,
  ],
  [
    7643811861122863391675032497197461253277456349658858402292366609151447579740n,
    7966758021277141390084387639007706296597837213361700710781421670326107044743n,
    6948275241446255407819689736335976334741531011842955690505723437143985966047n,
    16057479168603339473841717809004381746348842734219963194732172757192003265965n,
    0n,
  ],
];

// Perform round 1 commitment contribute
async () => {
    const { coef, commitment } = await DKGAdapterTest.round1RCommit();

  }

// Perform round 2 commitment contribute
async () => {
    const result = await DKGAdapterTest.round2Commit(
      commiteeIndex,
      commiteeCoef,
      commitmentsOfIndex,
      colCommitment0,
    );

  }

// Commitee request reveal one transaction
async () => {
    const result = await DKGAdapterTest.revealCommit(
      commiteeIndex,
      commiteeCoef,
      pkAddress,
      commitmentsOfIndex,
      colCommitment0,
      allEncrypteds,
    );

  };

============================
|| Initialize PivotAdapter ||
============================

// get from smart contract DKG. after round 1 commit, this is public data of DKG
export const PKCOMMITEE: TBabyJubPoint = [
  9230104626599243064899758455545826940353924657211481143808941656253944000277n,
  21437334619354716912008719913516183379896479638859445648697237162152540179004n,
];

// User input to deposit to protocol
export const V: bigint[] = [
  10000000000000000n,
  10000000000000000n,
  10000000000000000n,
  10000000000000000n,
];

export const Relayer: string = "0x19F96D5e33cDbADc7E16e060E6276274560bbAB1";

// Receive wallet
export const Recipient: string = "0x19F96D5e33cDbADc7E16e060E6276274560bbAB1";

// index of element in private array
export const IndexAmount: bigint = 0n;

export const FeeAmount: bigint = 1n;

// getting from relayer if user really have the private data
export const Tree: TTree = {
  root: "18191447278207921504252205132749046623391193605103681411307384056275326415582",
  pathElements: [
    "3042774122929058629117742057409317273972932196304097622662323601237587181833",
    "20431723124106178868087892767550358547234084221431521876290313514162412261281",
    "12691172665181799261366508275640388438953145545023451268408202178713879563495",
    "10015100543193608285627159378129881132856612593765837981928216905967396370518",
    "17749355866590679136479578122292062650730780924025117077499852936291363834358",
    "12294671195125736927152969230572786659107178459271008172455369995562382443984",
    "17243091879903699948042249137776802095963509839518144083110886934418922625082",
    "2655054374148387695361055329340738561118241108337951068774875401837898573480",
    "9282980216543830550228280650701982057342402908737452064215906421434522236474",
    "11457299105034543455790213447725010039018775064371264098543212759344937823391",
  ],
  pathIndices: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0],
};


const pivotAdapter = new PivotAdapter(PKCOMMITEE);

// Generate nullifier
async () => {
   const nullifier = await pivotAdapter.generateNullifier();
};

// Generate deposit params
async () => {
    const result = await pivotAdapter.deposit(
      nullifier,
      V,
    );

};

// Generate ZK input for withdraw operation.
async () => {
    const result = await pivotAdapter.withdraw(
      nullifier,
      Recipient,
      Relayer,
      V,
      IndexAmount,
      FeeAmount,
      Tree,
    );

};

// Generate ZK input for swap operation.
async () => {
    const result = await pivotAdapter.swap(
      nullifier,
      Recipient,
      Relayer,
      V,
      IndexAmount,
      FeeAmount,
      TokenOut,
      AmountOutMin,
      Tree,
    );

  };