@dorafactory/maci-sdk 0.0.10 → 0.0.12

package/README.md

@@ -116,8 +116,7 @@ const newRound = await client.createOracleMaciRound({
   title: 'Just for fun',
   description: 'some description',
   link: 'https://www.dorafactory.org',
-  maxVoter: '5',
-  maxOption: '5',
+  voteOptionMap: ['option1: A', 'option2: B', 'option3: C'],
   circuitType: MaciCircuitType.IP1V,
   whitelistEcosystem: 'cosmoshub',
   whitelistSnapshotHeight: '0',
@@ -146,3 +145,108 @@ For example, if a voter stakes 100000000 tokens and the slope value is 2500000,
 > 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.
+
+#### Sign Up and Vote in a Oracle MACI Round
+
+```typescript
+// 1. Generate MACI account
+const maciAccount = await client.circom.genKeypairFromSign(wallet, address);
+
+// 2. Get Oracle certificate (only for Oracle MACI)
+const certificate = await client.maci.requestOracleCertificate({
+  signer: wallet,
+  ecosystem: 'doravota', // or 'cosmoshub'
+  address,
+  contractAddress: 'dora1...',
+});
+
+// 3. Check Gas Station status
+let gasStationEnable = await client.maci.queryRoundGasStation({
+  contractAddress: 'dora1...',
+});
+
+// Wait for Gas Station to be enabled
+while (!gasStationEnable) {
+  await delay(1000); // Delay 1 second
+  gasStationEnable = await client.maci.queryRoundGasStation({
+    contractAddress: 'dora1...',
+  });
+}
+
+// 4. Sign up for voting
+const signupResponse = await client.maci.signup({
+  signer: wallet,
+  address,
+  contractAddress: 'dora1...',
+  oracleCertificate: {
+    amount: certificate.amount,
+    signature: certificate.signature,
+  },
+  gasStation: true, // Whether to use gas station
+});
+
+// 5. Get user state index
+const stateIdx = await client.maci.getStateIdxByPubKey({
+  contractAddress: 'dora1...',
+  pubKey: maciAccount.pubKey,
+});
+
+// 6. Cast vote
+const voteResponse = await client.maci.vote({
+  signer: wallet,
+  address,
+  stateIdx,
+  contractAddress: 'dora1...',
+  selectedOptions: [
+    { idx: 0, vc: 2 }, // Option index and voting weight
+    { idx: 1, vc: 1 },
+    { idx: 4, vc: 1 },
+  ],
+  operatorCoordPubKey: [
+    BigInt(roundInfo.coordinatorPubkeyX),
+    BigInt(roundInfo.coordinatorPubkeyY),
+  ],
+  gasStation: true,
+});
+```
+
+**Voting Rules:**
+
+MACI supports two voting rules:
+1. 1P1V (One Person One Vote): Each voting weight (vc) directly counts as votes
+2. QV (Quadratic Voting): The sum of squares of voting weights (vc) is consumed as total voting power
+
+Vote options format:
+```typescript
+selectedOptions: [
+  { idx: number, vc: number }, // idx: option index, vc: voting weight
+  ...
+]
+```
+
+Examples:
+```typescript
+// 1P1V mode example (total voting power: 4)
+const options1p1v = [
+  { idx: 0, vc: 2 }, // 2 votes for option 0
+  { idx: 1, vc: 1 }, // 1 vote for option 1
+  { idx: 4, vc: 1 }, // 1 vote for option 4
+]; 
+// Total voting power consumed = 2 + 1 + 1 = 4
+
+// QV mode example (total voting power: 6)
+const optionsQv = [
+  { idx: 0, vc: 2 }, // Consumes 4 voting power (2²)
+  { idx: 1, vc: 1 }, // Consumes 1 voting power (1²)
+  { idx: 2, vc: 1 }, // Consumes 1 voting power (1²)
+];
+// Total voting power consumed = 2² + 1² + 1² = 6
+```
+
+**Important Notes:**
+- Option indices (idx) must be unique
+- Voting weights (vc) must be positive integers
+- In QV mode, total voting power consumed is the sum of squares of voting weights
+- Total voting power consumed cannot exceed user's available voting credits
+- System automatically filters out options with zero voting weight
+- Voting options are automatically sorted by idx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorafactory/maci-sdk",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "SDK for interacting with maci",
   "keywords": [
     "maci",
@@ -36,7 +36,7 @@
     "@cosmjs/stargate": "^0.32.1",
     "assert": "^2.1.0",
     "bech32": "1.1.4",
-    "@dorafactory/circomlib": "^0.0.2",
+    "@dorafactory/circomlib": "^0.0.3",
     "colorts": "^0.1.63",
     "cosmjs-types": "^0.9.0",
     "blake-hash": "^2.0.0",