@snapshot-labs/snapshot.js 0.14.8 → 0.14.10

package/dist/snapshot.cjs.js

@@ -1722,7 +1722,7 @@ var networks = {
 		url: "https://explorer.celo.org"
 	},
 	start: 6599803,
-	logo: "ipfs://QmS2tVJ7rdJRe1NHXAi2L86yCbUwVVrmB2mHQeNdJxvQti"
+	logo: "ipfs://bafkreidvcofeczigbjr7ddapgdugwso6v2l4iolfxys7qg6kfvu2uduyva"
 },
 	"43113": {
 	key: "43113",
@@ -2664,12 +2664,51 @@ function irv(ballots, rounds) {
         ])
             .filter((ballot) => ballot[0].length > 0), rounds);
 }
+/**
+ * Runs the complete Instant Runoff Voting (IRV) algorithm and returns the final results.
+ *
+ * Executes all elimination rounds until a winner is determined or fewer than 3 candidates remain.
+ * Each round eliminates the candidate with the fewest votes and redistributes their votes
+ * to voters' next preferences.
+ *
+ * @param votes - Array of valid ranked choice votes to process
+ * @returns Array of tuples representing the final candidate rankings, sorted by vote count (highest first).
+ *          Each tuple contains [candidateIndex, [totalBalance, scoresArray]] where:
+ *          - totalBalance: Sum of voting power from all voters who support this candidate
+ *          - scoresArray: Breakdown of that voting power by voting strategy
+ *          The relationship: totalBalance === scoresArray.reduce((a,b) => a + b, 0)
+ *
+ * @example
+ * // Returns final results after IRV elimination rounds
+ * // [["2", [150, [60,50,40]]], ["1", [120, [70,30,20]]], ...]
+ * // Candidate 2 wins with 150 total voting power (60+50+40 from 3 strategies)
+ * // Candidate 1 has 120 total voting power (70+30+20 from 3 strategies)
+ */
 function getFinalRound(votes) {
     const rounds = irv(votes.map((vote) => [vote.choice, vote.balance, vote.scores]), []);
     const finalRound = rounds[rounds.length - 1];
     return finalRound.sortedByHighest;
 }
-function getScoresMethod(votes, proposal) {
+/**
+ * Converts IRV final results into a simple array of scores indexed by proposal choice order.
+ *
+ * Takes the ranked results from getFinalRound() (sorted by winner) and transforms them
+ * into an array where each position corresponds to the original proposal choice index.
+ * This allows easy lookup of any candidate's final vote total by their position in the proposal.
+ *
+ * @param votes - Array of valid ranked choice votes to process
+ * @param proposal - Proposal object containing the choices array
+ * @returns Array of total voting power for each choice, indexed by proposal order.
+ *          Position 0 = first choice's votes, position 1 = second choice's votes, etc.
+ *
+ * @example
+ * // proposal.choices = ['Alice', 'Bob', 'Carol', 'David']
+ * // After IRV: Bob won (150), David 2nd (120), Alice 3rd (100), Carol 4th (80)
+ * // Returns: [100, 150, 80, 120]
+ * //           ↑    ↑    ↑   ↑
+ * //        Alice Bob Carol David (proposal order)
+ */
+function getFinalScoresByChoice(votes, proposal) {
     const finalRound = getFinalRound(votes);
     return proposal.choices.map((choice, i) => finalRound
         .filter((res) => Number(res[0]) === i + 1)
@@ -2698,7 +2737,7 @@ class RankedChoiceVoting {
         return this.votes.filter((vote) => RankedChoiceVoting.isValidChoice(vote.choice, this.proposal.choices));
     }
     getScores() {
-        return getScoresMethod(this.getValidVotes(), this.proposal);
+        return getFinalScoresByChoice(this.getValidVotes(), this.proposal);
     }
     getScoresByStrategy() {
         const finalRound = getFinalRound(this.getValidVotes());
@@ -2708,15 +2747,56 @@ class RankedChoiceVoting {
                 .reduce((a, b) => a + (b[1][1][sI] || 0), 0);
         }));
     }
+    /**
+     * Returns the total voting power from all submitted votes, including invalid ones.
+     *
+     * This method sums the balance (voting power) from ALL votes submitted to the proposal,
+     * regardless of whether they have valid choice arrays. This is useful for calculating
+     * total participation, quorum requirements, and percentage of total voting power.
+     *
+     * Note: This differs from IRV final results which only include valid votes. Invalid votes
+     * are excluded from IRV calculations but their voting power is still counted here for
+     * participation metrics.
+     *
+     * @returns Total voting power from all votes (valid + invalid)
+     *
+     * @example
+     * // votes = [
+     * //   { choice: [1,2,3,4], balance: 1000 }, // Valid
+     * //   { choice: [1,5,2], balance: 500 },    // Invalid (index 5)
+     * //   { choice: [2,1,4,3], balance: 750 }   // Valid
+     * // ]
+     * // Returns: 2250 (includes invalid vote's 500 balance)
+     */
     getScoresTotal() {
         return this.votes.reduce((a, b) => a + b.balance, 0);
     }
+    /**
+     * Converts the selected choice indices into a human-readable string representation.
+     *
+     * Note: This method supports partial ranking where not all available choices
+     * need to be selected. The ordinal positions (1st, 2nd, etc.) reflect the
+     * order of valid selections only. Invalid choice indices are filtered out.
+     *
+     * @returns A formatted string showing the ranked choices with ordinal positions.
+     * Only valid choices are included, invalid indices are silently ignored.
+     *
+     * @example
+     * // With choices ['Alice', 'Bob', 'Carol', 'David'] and selected [1, 3, 2]
+     * // Returns: "(1st) Alice, (2nd) Carol, (3rd) Bob"
+     *
+     * @example
+     * // Partial ranking with choices ['Alice', 'Bob', 'Carol', 'David'] and selected [4, 1]
+     * // Returns: "(1st) David, (2nd) Alice"
+     *
+     * @example
+     * // With invalid choice index 5 in selected [1, 5]
+     * // Returns: "(1st) Alice" - invalid choice 5 is filtered out
+     */
     getChoiceString() {
         return this.selected
-            .map((choice) => {
-            if (this.proposal.choices[choice - 1])
-                return this.proposal.choices[choice - 1];
-        })
+            .map((choice) => this.proposal.choices[choice - 1])
+            .filter(Boolean)
             .map((el, i) => `(${getNumberWithOrdinal(i + 1)}) ${el}`)
             .join(', ');
     }
@@ -3095,59 +3175,76 @@ function parseStarknetResult(rawResult, functionAbi) {
         rawResult.length === 0) {
         return rawResult;
     }
-    const output = functionAbi.outputs[0];
-    const rawValue = rawResult[0];
+    // Parse each output according to its type
+    const outputs = functionAbi.outputs;
+    const results = [];
+    let rawIndex = 0; // Track position in rawResult array
     try {
-        switch (output.type) {
-            case 'core::felt252':
-                // Try to decode as shortString (for name, symbol)
-                try {
-                    return starknet$1.shortString.decodeShortString(rawValue);
-                }
-                catch (_a) {
-                    // If shortString decode fails, return as hex
-                    return rawValue;
-                }
-            // Unsigned integers
-            case 'core::integer::u8':
-            case 'core::integer::u16':
-            case 'core::integer::u32':
-            case 'core::integer::u64':
-                return parseInt(rawValue, 16);
-            case 'core::integer::u128':
-            case 'core::integer::usize':
-                return BigInt(rawValue).toString();
-            case 'core::integer::u256':
-                return starknet$1.uint256.uint256ToBN({
-                    low: rawValue,
-                    high: rawResult[1] || '0x0'
-                });
-            // Signed integers
-            case 'core::integer::i8':
-            case 'core::integer::i16':
-            case 'core::integer::i32':
-            case 'core::integer::i64':
-                return parseInt(rawValue, 16);
-            case 'core::integer::i128':
-                return BigInt(rawValue).toString();
-            // Boolean type
-            case 'core::bool':
-                return rawValue === '0x1' || rawValue === '0x01';
-            // Address types
-            case 'core::starknet::contract_address::ContractAddress':
-            case 'core::starknet::class_hash::ClassHash':
-            case 'core::starknet::storage_access::StorageAddress':
-                return rawValue;
-            // Byte array
-            case 'core::bytes_31::bytes31':
-                return rawValue;
-            default:
-                // Return raw value for unknown types
-                return rawValue;
+        for (let outputIndex = 0; outputIndex < outputs.length; outputIndex++) {
+            const output = outputs[outputIndex];
+            const rawValue = rawResult[rawIndex];
+            switch (output.type) {
+                case 'core::felt252':
+                    try {
+                        results.push(starknet$1.shortString.decodeShortString(rawValue));
+                    }
+                    catch (_a) {
+                        results.push(rawValue);
+                    }
+                    rawIndex++;
+                    break;
+                case 'core::integer::u8':
+                case 'core::integer::u16':
+                case 'core::integer::u32':
+                case 'core::integer::u64':
+                    results.push(parseInt(rawValue, 16));
+                    rawIndex++;
+                    break;
+                case 'core::integer::u128':
+                case 'core::integer::usize':
+                    results.push(BigInt(rawValue).toString());
+                    rawIndex++;
+                    break;
+                case 'core::integer::u256':
+                    results.push(starknet$1.uint256.uint256ToBN({
+                        low: rawValue,
+                        high: rawResult[rawIndex + 1] || '0x0'
+                    }));
+                    rawIndex += 2; // u256 uses two slots
+                    break;
+                case 'core::integer::i8':
+                case 'core::integer::i16':
+                case 'core::integer::i32':
+                case 'core::integer::i64':
+                    results.push(parseInt(rawValue, 16));
+                    rawIndex++;
+                    break;
+                case 'core::integer::i128':
+                    results.push(BigInt(rawValue).toString());
+                    rawIndex++;
+                    break;
+                case 'core::bool':
+                    results.push(rawValue === '0x1' || rawValue === '0x01');
+                    rawIndex++;
+                    break;
+                case 'core::starknet::contract_address::ContractAddress':
+                case 'core::starknet::class_hash::ClassHash':
+                case 'core::starknet::storage_access::StorageAddress':
+                    results.push(rawValue);
+                    rawIndex++;
+                    break;
+                case 'core::bytes_31::bytes31':
+                    results.push(rawValue);
+                    rawIndex++;
+                    break;
+                default:
+                    results.push(rawValue);
+                    rawIndex++;
+            }
         }
+        return results;
     }
     catch (_b) {
-        // Fallback to raw result if parsing fails
         return rawResult;
     }
 }
@@ -3200,7 +3297,8 @@ function multicall$1(address_1, provider_1, abi_1, calls_1, limit_1) {
         return callResults.map((result, index) => {
             const [, functionName] = calls[index];
             const functionAbi = abi.find((item) => item.name === functionName);
-            return [parseStarknetResult(result, functionAbi)];
+            const parsedResult = parseStarknetResult(result, functionAbi);
+            return parsedResult;
         });
     });
 }
@@ -3639,7 +3737,8 @@ function getScores(space_1, strategies_1, network_1, addresses_1) {
         }
     });
 }
-function getVp(address, network, strategies, snapshot, space, delegation, options) {
+function getVp(address, network, strategies, snapshot, space, delegation, // @deprecated - kept for backward compatibility for integrators using this function, no longer sent to API
+options) {
     return __awaiter(this, void 0, void 0, function* () {
         const { url, headers } = formatScoreAPIUrl(options === null || options === void 0 ? void 0 : options.url);
         if (!isValidAddress(address)) {
@@ -3666,8 +3765,7 @@ function getVp(address, network, strategies, snapshot, space, delegation, option
                     network,
                     strategies,
                     snapshot,
-                    space,
-                    delegation
+                    space
                 }
             })
         };

package/dist/snapshot.esm.js

@@ -1712,7 +1712,7 @@ var networks = {
 		url: "https://explorer.celo.org"
 	},
 	start: 6599803,
-	logo: "ipfs://QmS2tVJ7rdJRe1NHXAi2L86yCbUwVVrmB2mHQeNdJxvQti"
+	logo: "ipfs://bafkreidvcofeczigbjr7ddapgdugwso6v2l4iolfxys7qg6kfvu2uduyva"
 },
 	"43113": {
 	key: "43113",
@@ -2654,12 +2654,51 @@ function irv(ballots, rounds) {
         ])
             .filter((ballot) => ballot[0].length > 0), rounds);
 }
+/**
+ * Runs the complete Instant Runoff Voting (IRV) algorithm and returns the final results.
+ *
+ * Executes all elimination rounds until a winner is determined or fewer than 3 candidates remain.
+ * Each round eliminates the candidate with the fewest votes and redistributes their votes
+ * to voters' next preferences.
+ *
+ * @param votes - Array of valid ranked choice votes to process
+ * @returns Array of tuples representing the final candidate rankings, sorted by vote count (highest first).
+ *          Each tuple contains [candidateIndex, [totalBalance, scoresArray]] where:
+ *          - totalBalance: Sum of voting power from all voters who support this candidate
+ *          - scoresArray: Breakdown of that voting power by voting strategy
+ *          The relationship: totalBalance === scoresArray.reduce((a,b) => a + b, 0)
+ *
+ * @example
+ * // Returns final results after IRV elimination rounds
+ * // [["2", [150, [60,50,40]]], ["1", [120, [70,30,20]]], ...]
+ * // Candidate 2 wins with 150 total voting power (60+50+40 from 3 strategies)
+ * // Candidate 1 has 120 total voting power (70+30+20 from 3 strategies)
+ */
 function getFinalRound(votes) {
     const rounds = irv(votes.map((vote) => [vote.choice, vote.balance, vote.scores]), []);
     const finalRound = rounds[rounds.length - 1];
     return finalRound.sortedByHighest;
 }
-function getScoresMethod(votes, proposal) {
+/**
+ * Converts IRV final results into a simple array of scores indexed by proposal choice order.
+ *
+ * Takes the ranked results from getFinalRound() (sorted by winner) and transforms them
+ * into an array where each position corresponds to the original proposal choice index.
+ * This allows easy lookup of any candidate's final vote total by their position in the proposal.
+ *
+ * @param votes - Array of valid ranked choice votes to process
+ * @param proposal - Proposal object containing the choices array
+ * @returns Array of total voting power for each choice, indexed by proposal order.
+ *          Position 0 = first choice's votes, position 1 = second choice's votes, etc.
+ *
+ * @example
+ * // proposal.choices = ['Alice', 'Bob', 'Carol', 'David']
+ * // After IRV: Bob won (150), David 2nd (120), Alice 3rd (100), Carol 4th (80)
+ * // Returns: [100, 150, 80, 120]
+ * //           ↑    ↑    ↑   ↑
+ * //        Alice Bob Carol David (proposal order)
+ */
+function getFinalScoresByChoice(votes, proposal) {
     const finalRound = getFinalRound(votes);
     return proposal.choices.map((choice, i) => finalRound
         .filter((res) => Number(res[0]) === i + 1)
@@ -2688,7 +2727,7 @@ class RankedChoiceVoting {
         return this.votes.filter((vote) => RankedChoiceVoting.isValidChoice(vote.choice, this.proposal.choices));
     }
     getScores() {
-        return getScoresMethod(this.getValidVotes(), this.proposal);
+        return getFinalScoresByChoice(this.getValidVotes(), this.proposal);
     }
     getScoresByStrategy() {
         const finalRound = getFinalRound(this.getValidVotes());
@@ -2698,15 +2737,56 @@ class RankedChoiceVoting {
                 .reduce((a, b) => a + (b[1][1][sI] || 0), 0);
         }));
     }
+    /**
+     * Returns the total voting power from all submitted votes, including invalid ones.
+     *
+     * This method sums the balance (voting power) from ALL votes submitted to the proposal,
+     * regardless of whether they have valid choice arrays. This is useful for calculating
+     * total participation, quorum requirements, and percentage of total voting power.
+     *
+     * Note: This differs from IRV final results which only include valid votes. Invalid votes
+     * are excluded from IRV calculations but their voting power is still counted here for
+     * participation metrics.
+     *
+     * @returns Total voting power from all votes (valid + invalid)
+     *
+     * @example
+     * // votes = [
+     * //   { choice: [1,2,3,4], balance: 1000 }, // Valid
+     * //   { choice: [1,5,2], balance: 500 },    // Invalid (index 5)
+     * //   { choice: [2,1,4,3], balance: 750 }   // Valid
+     * // ]
+     * // Returns: 2250 (includes invalid vote's 500 balance)
+     */
     getScoresTotal() {
         return this.votes.reduce((a, b) => a + b.balance, 0);
     }
+    /**
+     * Converts the selected choice indices into a human-readable string representation.
+     *
+     * Note: This method supports partial ranking where not all available choices
+     * need to be selected. The ordinal positions (1st, 2nd, etc.) reflect the
+     * order of valid selections only. Invalid choice indices are filtered out.
+     *
+     * @returns A formatted string showing the ranked choices with ordinal positions.
+     * Only valid choices are included, invalid indices are silently ignored.
+     *
+     * @example
+     * // With choices ['Alice', 'Bob', 'Carol', 'David'] and selected [1, 3, 2]
+     * // Returns: "(1st) Alice, (2nd) Carol, (3rd) Bob"
+     *
+     * @example
+     * // Partial ranking with choices ['Alice', 'Bob', 'Carol', 'David'] and selected [4, 1]
+     * // Returns: "(1st) David, (2nd) Alice"
+     *
+     * @example
+     * // With invalid choice index 5 in selected [1, 5]
+     * // Returns: "(1st) Alice" - invalid choice 5 is filtered out
+     */
     getChoiceString() {
         return this.selected
-            .map((choice) => {
-            if (this.proposal.choices[choice - 1])
-                return this.proposal.choices[choice - 1];
-        })
+            .map((choice) => this.proposal.choices[choice - 1])
+            .filter(Boolean)
             .map((el, i) => `(${getNumberWithOrdinal(i + 1)}) ${el}`)
             .join(', ');
     }
@@ -3085,59 +3165,76 @@ function parseStarknetResult(rawResult, functionAbi) {
         rawResult.length === 0) {
         return rawResult;
     }
-    const output = functionAbi.outputs[0];
-    const rawValue = rawResult[0];
+    // Parse each output according to its type
+    const outputs = functionAbi.outputs;
+    const results = [];
+    let rawIndex = 0; // Track position in rawResult array
     try {
-        switch (output.type) {
-            case 'core::felt252':
-                // Try to decode as shortString (for name, symbol)
-                try {
-                    return shortString.decodeShortString(rawValue);
-                }
-                catch (_a) {
-                    // If shortString decode fails, return as hex
-                    return rawValue;
-                }
-            // Unsigned integers
-            case 'core::integer::u8':
-            case 'core::integer::u16':
-            case 'core::integer::u32':
-            case 'core::integer::u64':
-                return parseInt(rawValue, 16);
-            case 'core::integer::u128':
-            case 'core::integer::usize':
-                return BigInt(rawValue).toString();
-            case 'core::integer::u256':
-                return uint256.uint256ToBN({
-                    low: rawValue,
-                    high: rawResult[1] || '0x0'
-                });
-            // Signed integers
-            case 'core::integer::i8':
-            case 'core::integer::i16':
-            case 'core::integer::i32':
-            case 'core::integer::i64':
-                return parseInt(rawValue, 16);
-            case 'core::integer::i128':
-                return BigInt(rawValue).toString();
-            // Boolean type
-            case 'core::bool':
-                return rawValue === '0x1' || rawValue === '0x01';
-            // Address types
-            case 'core::starknet::contract_address::ContractAddress':
-            case 'core::starknet::class_hash::ClassHash':
-            case 'core::starknet::storage_access::StorageAddress':
-                return rawValue;
-            // Byte array
-            case 'core::bytes_31::bytes31':
-                return rawValue;
-            default:
-                // Return raw value for unknown types
-                return rawValue;
+        for (let outputIndex = 0; outputIndex < outputs.length; outputIndex++) {
+            const output = outputs[outputIndex];
+            const rawValue = rawResult[rawIndex];
+            switch (output.type) {
+                case 'core::felt252':
+                    try {
+                        results.push(shortString.decodeShortString(rawValue));
+                    }
+                    catch (_a) {
+                        results.push(rawValue);
+                    }
+                    rawIndex++;
+                    break;
+                case 'core::integer::u8':
+                case 'core::integer::u16':
+                case 'core::integer::u32':
+                case 'core::integer::u64':
+                    results.push(parseInt(rawValue, 16));
+                    rawIndex++;
+                    break;
+                case 'core::integer::u128':
+                case 'core::integer::usize':
+                    results.push(BigInt(rawValue).toString());
+                    rawIndex++;
+                    break;
+                case 'core::integer::u256':
+                    results.push(uint256.uint256ToBN({
+                        low: rawValue,
+                        high: rawResult[rawIndex + 1] || '0x0'
+                    }));
+                    rawIndex += 2; // u256 uses two slots
+                    break;
+                case 'core::integer::i8':
+                case 'core::integer::i16':
+                case 'core::integer::i32':
+                case 'core::integer::i64':
+                    results.push(parseInt(rawValue, 16));
+                    rawIndex++;
+                    break;
+                case 'core::integer::i128':
+                    results.push(BigInt(rawValue).toString());
+                    rawIndex++;
+                    break;
+                case 'core::bool':
+                    results.push(rawValue === '0x1' || rawValue === '0x01');
+                    rawIndex++;
+                    break;
+                case 'core::starknet::contract_address::ContractAddress':
+                case 'core::starknet::class_hash::ClassHash':
+                case 'core::starknet::storage_access::StorageAddress':
+                    results.push(rawValue);
+                    rawIndex++;
+                    break;
+                case 'core::bytes_31::bytes31':
+                    results.push(rawValue);
+                    rawIndex++;
+                    break;
+                default:
+                    results.push(rawValue);
+                    rawIndex++;
+            }
         }
+        return results;
     }
     catch (_b) {
-        // Fallback to raw result if parsing fails
         return rawResult;
     }
 }
@@ -3190,7 +3287,8 @@ function multicall$1(address_1, provider_1, abi_1, calls_1, limit_1) {
         return callResults.map((result, index) => {
             const [, functionName] = calls[index];
             const functionAbi = abi.find((item) => item.name === functionName);
-            return [parseStarknetResult(result, functionAbi)];
+            const parsedResult = parseStarknetResult(result, functionAbi);
+            return parsedResult;
         });
     });
 }
@@ -3629,7 +3727,8 @@ function getScores(space_1, strategies_1, network_1, addresses_1) {
         }
     });
 }
-function getVp(address, network, strategies, snapshot, space, delegation, options) {
+function getVp(address, network, strategies, snapshot, space, delegation, // @deprecated - kept for backward compatibility for integrators using this function, no longer sent to API
+options) {
     return __awaiter(this, void 0, void 0, function* () {
         const { url, headers } = formatScoreAPIUrl(options === null || options === void 0 ? void 0 : options.url);
         if (!isValidAddress(address)) {
@@ -3656,8 +3755,7 @@ function getVp(address, network, strategies, snapshot, space, delegation, option
                     network,
                     strategies,
                     snapshot,
-                    space,
-                    delegation
+                    space
                 }
             })
         };