@dorafactory/maci-sdk 0.0.3 → 0.0.5

package/README.md

@@ -1 +1,128 @@
-# Maci Indexer Client
+# Maci Client
+
+MACI (Minimal Anti-Collusion Infrastructure) client SDK for interacting with MACI contracts.
+
+## Installation
+
+```bash
+npm install @dorafactory/maci-sdk
+```
+
+## Usage
+
+### Initialize Client
+
+```typescript
+import { MaciClient } from '@dorafactory/maci-sdk';
+
+const client = new MaciClient({
+  network: 'testnet', // or 'mainnet'
+});
+```
+
+### Query Functions
+
+#### Query Account Balance
+```typescript
+const balance = await client.balanceOf('dora1...');
+```
+
+#### Query Round Information
+```typescript
+// Query round by ID
+const round = await client.getRoundById('dora1...');
+
+// Get list of rounds
+const rounds = await client.getRounds('first', 10);
+
+// Query rounds by status
+const roundsByStatus = await client.getRoundsByStatus('Created', 'first', 10);
+
+// Query rounds by circuit name
+const roundsByCircuit = await client.getRoundsByCircuitName('amaci-qv', 'first', 10);
+
+// Query rounds by operator address
+const roundsByOperator = await client.getRoundsByOperator('dora1...', 'first', 10);
+```
+
+#### Query Operator Information
+```typescript
+// Query operator by address
+const operator = await client.getOperatorByAddress('dora1...');
+
+// Get list of operators
+const operators = await client.getOperators('first', 10);
+```
+
+#### Query Circuit Information
+```typescript
+// Query circuit by name
+const circuit = await client.getCircuitByName('amaci-qv');
+
+// Get all circuits
+const circuits = await client.getCircuits();
+```
+
+#### Query Transaction Information
+```typescript
+// Query transaction by hash
+const transaction = await client.getTransactionByHash('HASH...');
+
+// Get list of transactions
+const transactions = await client.getTransactions('first', 10);
+
+// Query transactions by contract address
+const txByContract = await client.getTransactionsByContractAddress('dora1...', 'first', 10);
+```
+
+#### Query Proof Information
+```typescript
+const proof = await client.getProofByContractAddress('dora1...');
+```
+
+### Contract Interactions
+
+#### Create New Oracle Maci Round
+```typescript
+const wallet = await DirectSecp256k1Wallet.fromKey(
+  Buffer.from(privateKey, 'hex'),
+  'dora'
+);
+
+const newRound = await client.createOracleMaciRound({
+  signer: wallet,
+  operatorPubkey: '0e752c...',
+  startVoting: new Date(),
+  endVoting: new Date(new Date().getTime() + 10 * 60 * 1000),
+  title: 'Just for fun',
+  description: 'some description',
+  link: 'https://www.dorafactory.org',
+  maxVoter: '5',
+  maxOption: '5',
+  circuitType: MaciCircuitType.IP1V,
+  whitelistEcosystem: 'cosmoshub',
+  whitelistSnapshotHeight: '0',
+  whitelistVotingPowerArgs: {
+    mode: 'slope',
+    slope: '1000000',
+    threshold: '1000000',
+  },
+});
+```
+
+**Note:** 
+- The `operatorPubkey` is the public key of the operator. It is the compressed public key of the operator's private key.
+- The `whitelistEcosystem` is the ecosystem of the whitelist (e.g. 'cosmoshub'). Only wallet addresses that have staked tokens in the specified ecosystem before the snapshot block height will be eligible to become voters.
+- The `whitelistSnapshotHeight` is the snapshot block height for checking voter eligibility. The minimum valid height is 23,342,001. If set to "0", the round will evaluate the voter's stake at the time of signup.
+- The `whitelistVotingPowerArgs` configures how voting power is calculated:
+  - `mode`: Can be either 'slope' or 'threshold'
+    - 'slope' mode: Calculates voice credits based on each voter's stake amount using the formula: voice credits = staked tokens / slope value
+    - 'threshold' mode: Equally assigns 1 voice credit to voters whose stake exceeds the specified threshold
+  - `slope`: The slope value for calculating voice credits in slope mode (e.g. 1000000)
+  - `threshold`: The minimum stake threshold in threshold mode (e.g. 1000000)
+
+For example, if a voter stakes 100000000 tokens and the slope value is 2500000, the voter will be assigned 40 voice credits.
+
+> The 1,000,000 reference value here is the precision of cosmoshub, which is 6 bits, and doravota, which is 18 bits, so when you want to pick doravota's staker as a whitelist and ask them to pledge 1DORA to convert 1vote, you need to set the scope to 1000000000000000000 (10**18). Note that currently only cosmoshub and doravota are supported as ecosystem options.
+> 
+> One detail, here the slope is calculated by rounding down.

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export { Circuit } from './libs/query';
 export { Operator } from './libs/query';
 export { Proof } from './libs/query';
 export { Transaction } from './libs/query';
+export * from './utils';

package/dist/index.js

@@ -34,7 +34,11 @@ __export(src_exports, {
   Round: () => Round,
   Transaction: () => Transaction,
   circuits: () => circuits,
+  compressPublicKey: () => compressPublicKey,
+  decompressPublicKey: () => decompressPublicKey,
   getDefaultParams: () => getDefaultParams,
+  hexToDecimalString: () => hexToDecimalString,
+  isValidAddress: () => isValidAddress,
   validator_operator_set: () => validator_operator_set
 });
 module.exports = __toCommonJS(src_exports);
@@ -557,6 +561,34 @@ function verifyIsBech32(address) {
 function isValidAddress(address) {
   return address.startsWith("dora") && verifyIsBech32(address) === void 0;
 }
+function hexToDecimalString(hexString) {
+  const decimalString = BigInt("0x" + hexString).toString(10);
+  return decimalString;
+}
+function padWithZerosIfNeeded(inputString) {
+  if (inputString.length === 64) {
+    return inputString;
+  } else if (inputString.length < 64) {
+    const zerosToAdd = 64 - inputString.length;
+    const zeroPadding = "0".repeat(zerosToAdd);
+    return zeroPadding + inputString;
+  }
+  throw new Error("Invalid input string length");
+}
+function decompressPublicKey(compressedPubkey) {
+  const x = compressedPubkey.slice(0, 64);
+  const y = compressedPubkey.slice(64);
+  return {
+    x: hexToDecimalString(x),
+    y: hexToDecimalString(y)
+  };
+}
+function compressPublicKey(decompressedPubkey) {
+  const x = decompressedPubkey[0];
+  const y = decompressedPubkey[1];
+  const compressedPubkey = padWithZerosIfNeeded(x.toString(16)) + padWithZerosIfNeeded(y.toString(16));
+  return compressedPubkey;
+}
 
 // src/libs/query/operator.ts
 var Operator = class {
@@ -3669,18 +3701,6 @@ function getContractParams(type, circuitType, proofSystem, maxVoter, maxOption)
       };
   }
 }
-function hexToDecimalString(hexString) {
-  const decimalString = BigInt("0x" + hexString).toString(10);
-  return decimalString;
-}
-function parsePubkey(publickKey) {
-  const x = publickKey.slice(0, 64);
-  const y = publickKey.slice(64);
-  return {
-    x: hexToDecimalString(x),
-    y: hexToDecimalString(y)
-  };
-}
 
 // src/libs/contract/contract.ts
 var Contract = class {
@@ -3688,12 +3708,16 @@ var Contract = class {
     rpcEndpoint,
     registryAddress,
     maciCodeId,
-    oracleCodeId
+    oracleCodeId,
+    feegrantOperator,
+    whitelistBackendPubkey
   }) {
     this.rpcEndpoint = rpcEndpoint;
     this.registryAddress = registryAddress;
     this.maciCodeId = maciCodeId;
     this.oracleCodeId = oracleCodeId;
+    this.feegrantOperator = feegrantOperator;
+    this.whitelistBackendPubkey = whitelistBackendPubkey;
   }
   async createAMaciRound({
     signer,
@@ -3769,7 +3793,7 @@ var Contract = class {
     const end_time = (endVoting.getTime() * 10 ** 6).toString();
     const [{ address }] = await signer.getAccounts();
     const client = await createContractClientByWallet(this.rpcEndpoint, signer);
-    const { x: operatorPubkeyX, y: operatorPubkeyY } = parsePubkey(operatorPubkey);
+    const { x: operatorPubkeyX, y: operatorPubkeyY } = decompressPublicKey(operatorPubkey);
     const {
       parameters,
       groth16ProcessVkey,
@@ -3825,17 +3849,15 @@ var Contract = class {
     maxVoter,
     maxOption,
     circuitType,
-    whitelistBackendPubkey,
     whitelistEcosystem,
     whitelistSnapshotHeight,
-    whitelistVotingPowerArgs,
-    feegrantOperator
+    whitelistVotingPowerArgs
   }) {
     const start_time = (startVoting.getTime() * 1e6).toString();
     const end_time = (endVoting.getTime() * 1e6).toString();
     const [{ address }] = await signer.getAccounts();
     const client = await createContractClientByWallet(this.rpcEndpoint, signer);
-    const { x: operatorPubkeyX, y: operatorPubkeyY } = parsePubkey(operatorPubkey);
+    const { x: operatorPubkeyX, y: operatorPubkeyY } = decompressPublicKey(operatorPubkey);
     const {
       parameters,
       groth16ProcessVkey,
@@ -3870,14 +3892,14 @@ var Contract = class {
         plonk_process_vkey: plonkProcessVkey,
         plonk_tally_vkey: plonkTallyVkey,
         max_vote_options: maxOption,
-        whitelist_backend_pubkey: whitelistBackendPubkey,
+        whitelist_backend_pubkey: this.whitelistBackendPubkey,
         whitelist_ecosystem: whitelistEcosystem,
         whitelist_snapshot_height: whitelistSnapshotHeight,
         whitelist_voting_power_args: whitelistVotingPowerArgs,
         circuit_type: maciVoteType,
         certification_system: maciCertSystem,
         qtr_lib: QTR_LIB,
-        feegrant_operator: feegrantOperator
+        feegrant_operator: this.feegrantOperator
       },
       "[Oracle MACI]" + title,
       "auto"
@@ -3954,7 +3976,9 @@ var MaciClient2 = class {
     maciCodeId,
     oracleCodeId,
     customFetch,
-    defaultOptions
+    defaultOptions,
+    feegrantOperator,
+    whitelistBackendPubkey
   }) {
     const defaultParams = getDefaultParams(network);
     this.rpcEndpoint = rpcEndpoint || defaultParams.rpcEndpoint;
@@ -3963,6 +3987,8 @@ var MaciClient2 = class {
     this.registryAddress = registryAddress || defaultParams.registryAddress;
     this.maciCodeId = maciCodeId || defaultParams.maciCodeId;
     this.oracleCodeId = oracleCodeId || defaultParams.oracleCodeId;
+    this.feegrantOperator = feegrantOperator || defaultParams.oracleFeegrantOperator;
+    this.whitelistBackendPubkey = whitelistBackendPubkey || defaultParams.oracleWhitelistBackendPubkey;
     this.http = new Http(
       this.apiEndpoint,
       this.restEndpoint,
@@ -3979,7 +4005,9 @@ var MaciClient2 = class {
       rpcEndpoint: this.rpcEndpoint,
       registryAddress: this.registryAddress,
       maciCodeId: this.maciCodeId,
-      oracleCodeId: this.oracleCodeId
+      oracleCodeId: this.oracleCodeId,
+      feegrantOperator: this.feegrantOperator,
+      whitelistBackendPubkey: this.whitelistBackendPubkey
     });
   }
   async oracleMaciClient({
@@ -4175,7 +4203,11 @@ var MaciClient2 = class {
   Round,
   Transaction,
   circuits,
+  compressPublicKey,
+  decompressPublicKey,
   getDefaultParams,
+  hexToDecimalString,
+  isValidAddress,
   validator_operator_set
 });
 //# sourceMappingURL=index.js.map