From 0c7864cbcd131ed173bbe7c9a85d3801eb3fb44e Mon Sep 17 00:00:00 2001 From: marcvelmer Date: Fri, 1 Mar 2024 11:39:07 +0000 Subject: [PATCH] Update vocdoni-sdk docs by commit 0849099 --- docs/get-started/01-intro.md | 441 +++++++++++++++++- docs/sdk/AccountAPI.mdx | 63 ++- docs/sdk/AccountService.mdx | 64 +++ docs/sdk/AnonymousService.mdx | 73 +++ docs/sdk/AnonymousVote.mdx | 29 ++ docs/sdk/ApprovalElection.mdx | 29 ++ docs/sdk/ArchivedCensus.mdx | 33 ++ docs/sdk/ArchivedElection.mdx | 29 ++ docs/sdk/BudgetElection.mdx | 29 ++ docs/sdk/Census3CensusAPI.mdx | 25 +- docs/sdk/Census3ServiceAPI.mdx | 43 ++ docs/sdk/Census3StrategyAPI.mdx | 141 +++++- docs/sdk/Census3TokenAPI.mdx | 37 +- docs/sdk/CensusAPI.mdx | 75 ++- docs/sdk/CensusImportExport.mdx | 15 + ...ffchainCensusProof.mdx => CensusProof.mdx} | 1 - docs/sdk/CensusService.mdx | 158 +++++++ docs/sdk/ChainService.mdx | 115 +++++ docs/sdk/CspService.mdx | 27 ++ docs/sdk/CspVote.mdx | 3 +- docs/sdk/ElectionAPI.mdx | 21 +- docs/sdk/ElectionCore.mdx | 36 -- docs/sdk/ElectionService.mdx | 155 ++++++ docs/sdk/FaucetAPI.mdx | 3 +- docs/sdk/FaucetOptions.mdx | 4 +- docs/sdk/FaucetService.mdx | 63 +++ docs/sdk/FileService.mdx | 49 ++ docs/sdk/MultiChoiceElection.mdx | 29 ++ docs/sdk/Service.mdx | 23 + docs/sdk/Signing.mdx | 3 +- docs/sdk/TokenCensus.mdx | 3 +- docs/sdk/TxWaitOptions.mdx | 4 +- docs/sdk/VocdoniCensus3Client.mdx | 162 +++++-- docs/sdk/VocdoniSDKClient.mdx | 363 ++++++++------ docs/sdk/VoteCore.mdx | 2 +- docs/sdk/VoteService.mdx | 62 +++ docs/sdk/ZkAPI.mdx | 61 +++ docs/sdk/changelog.md | 246 +++++++++- docs/sdk/sdk.md | 431 ++++++++++++++++- docs/sdk/sidebars-api.js | 27 +- 40 files changed, 2909 insertions(+), 268 deletions(-) create mode 100644 docs/sdk/AccountService.mdx create mode 100644 docs/sdk/AnonymousService.mdx create mode 100644 docs/sdk/AnonymousVote.mdx create mode 100644 docs/sdk/ApprovalElection.mdx create mode 100644 docs/sdk/ArchivedCensus.mdx create mode 100644 docs/sdk/ArchivedElection.mdx create mode 100644 docs/sdk/BudgetElection.mdx create mode 100644 docs/sdk/Census3ServiceAPI.mdx create mode 100644 docs/sdk/CensusImportExport.mdx rename docs/sdk/{OffchainCensusProof.mdx => CensusProof.mdx} (85%) create mode 100644 docs/sdk/CensusService.mdx create mode 100644 docs/sdk/ChainService.mdx create mode 100644 docs/sdk/CspService.mdx create mode 100644 docs/sdk/ElectionService.mdx create mode 100644 docs/sdk/FaucetService.mdx create mode 100644 docs/sdk/FileService.mdx create mode 100644 docs/sdk/MultiChoiceElection.mdx create mode 100644 docs/sdk/Service.mdx create mode 100644 docs/sdk/VoteService.mdx create mode 100644 docs/sdk/ZkAPI.mdx diff --git a/docs/get-started/01-intro.md b/docs/get-started/01-intro.md index cb41d5e7b..de25da8d8 100644 --- a/docs/get-started/01-intro.md +++ b/docs/get-started/01-intro.md @@ -1,3 +1,18 @@ +

+ +

+ +
+ +![npm](https://img.shields.io/npm/v/%40vocdoni%2Fsdk) +![GitHub commit activity (main)](https://img.shields.io/github/commit-activity/m/vocdoni/vocdoni-sdk) +[![Example workflow](https://github.com/vocdoni/vocdoni-sdk/actions/workflows/examples.yml/badge.svg)](https://vocdoni.github.io/vocdoni-sdk/) +![Main workflow](https://github.com/vocdoni/vocdoni-sdk/actions/workflows/main.yml/badge.svg) +[![Join Discord](https://img.shields.io/badge/discord-join%20chat-blue.svg)](https://discord.gg/xFTh8Np2ga) +[![Twitter Follow](https://img.shields.io/twitter/follow/vocdoni.svg?style=social&label=Follow)](https://twitter.com/vocdoni) + +
+ # Vocdoni SDK The Vocdoni SDK is a convenient way to interact with the Vocdoni Protocol @@ -236,8 +251,8 @@ const election = Election.from({ voteType: { uniqueChoices: false, // if the choices are unique when voting maxVoteOverwrites: 0, // number of times a vote can be overwritten - costFromWeight: false, // for quadratic voting - costExponent: 10000, // for quadratic voting + costFromWeight: false, // for cuadrating voting + costExponent: 10000, // for cuadrating voting } }) ~~~ @@ -316,7 +331,7 @@ More information can be found in the [documentation][ranked voting documentation #### Estimate election cost -This is a fast function (most times will resolve automatically) which allows to estimate an election price in tokens: +This is a fast function (most times will resolve automatically) which allows to estimate a election price in tokens: ~~~ts (async () => { @@ -338,7 +353,7 @@ This function returns the exact election price in tokens: ### Fetching election info -You can always access an election information and metadata using `fetchElection`: +You can always access a election information and metadata using `fetchElection`: ~~~ts (async () => { @@ -503,7 +518,7 @@ console.log(userWallet) // address is 0x8AF1b3EDB817b5854e3311d583905a3421F49829 The SDK comes with an implementation of the common handler API of a CSP which is explained [here](https://github.com/vocdoni/blind-csp#api). -For creating a CSP based election, a `CspCensus` has to be set to the election. This census needs the +For creating a CSP based election, a `CspCensus` has to be set to the election. This census need the CSP public key (`CSP_PUBKEY` in the example) and the CSP Url (`CSP_URL` in the example). ~~~ts @@ -547,9 +562,421 @@ const vote = client.cspVote(new Vote([index % 2]), signature); const voteId = await client.submitVote(vote); ~~~ +## Census3 + +### What is Census3? + +Census3 is an API service to create censuses for elections with holders of a single token or a combination of them. +The service creates a list of holder addresses and balances and keeps it updated in real time, for every registered token. +Then, it allows creating a merkle tree census (compatible with [Vocdoni](https://vocdoni.io/)) with those holders, using their balances as vote weights. + +More information about Census3 can be found [here](https://github.com/vocdoni/census3). + +### Using Census3 + +The SDK comes with an implementation of the [Census3 API](https://github.com/vocdoni/census3/blob/main/api/README.md). + +#### Creating a Census3 client + +~~~ts +const client = new VocdoniCensus3Client({ + env: EnvOptions.DEV // dev environment +}) +~~~ + +#### Getting basic service information + +~~~ts +// Get the supported chains +const supportedChains = await client.getSupportedChains(); +// [ +// { +// "chainID": 1, +// "shortName": "eth", +// "name": "Ethereum Mainnet" +// }, +// { +// "chainID": 5, +// "shortName": "gor", +// "name": "Goerli" +// }, +// { +// "chainID": 137, +// "shortName": "matic", +// "name": "Polygon Mainnet" +// }, +// { +// "chainID": 80001, +// "shortName": "maticmum", +// "name": "Mumbai" +// } +// ] +~~~ + +~~~ts +// Get the supported token types +const supportedTypes = await client.getSupportedTypes(); +// ["erc20", "erc777", "poap", "unknown", "erc721burned", "erc1155", "nation3", "want", "erc721"] +~~~ + +#### Getting tokens information and creating them + +~~~ts +// Get the supported tokens +const supportedTokens = await client.getSupportedTokens(); +// [ +// { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 10886913, +// "symbol": "YAM", +// "totalSupply": "", +// "name": "YAM", +// "status": { +// "atBlock": 18565762, +// "synced": true, +// "progress": 100 +// }, +// "size": 14999, +// "defaultStrategy": 19, +// "chainID": 1, +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// }, +// { +// "ID": "0x0b38210ea11411557c13457D4dA7dC6ea731B88a", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 11203771, +// "symbol": "API3", +// "totalSupply": "", +// "name": "API3", +// "status": { +// "atBlock": 18565763, +// "synced": true, +// "progress": 100 +// }, +// "size": 51178, +// "defaultStrategy": 8, +// "chainID": 1, +// "chainAddress": "eth:0x0b38210ea11411557c13457D4dA7dC6ea731B88a" +// }, +// ... +// ] +~~~ + +~~~ts +// Get a token by its ID (address) and chain identifier +const token = await client.getToken('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +// { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 10886913, +// "symbol": "YAM", +// "totalSupply": "15164231312592159866595366", +// "name": "YAM", +// "status": { +// "atBlock": 18565783, +// "synced": true, +// "progress": 100 +// }, +// "size": 14999, +// "defaultStrategy": 19, +// "chainID": 1, +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "tags": [] +// } +~~~ + +~~~ts +// Check if a holder is registered for a given token +const token = await client.isHolderInToken( + '0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', + 1, + '0x111000000000000000000000000000000000dEaD' +); +// false +~~~ + +~~~ts +// Creates a new token by passing the address, the type and the chain identifier +const token = await client.createToken('0xa117000000f279d81a1d3cc75430faa017fa5a2e', 'erc20', 1); +~~~ + +#### Getting strategies information and creating them + +~~~ts +// Get the supported strategies +const supportedStrategies = await client.getStrategies(); +// [ +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// }, +// { +// "ID": 2, +// "alias": "Default strategy for token UNI", +// "predicate": "UNI", +// "uri": "ipfs://bafybeiesxbsbvp2agcuolezec6hvimntqdg3w43xs62mecdj2fyeh5anxu", +// "tokens": { +// "UNI": { +// "ID": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984" +// } +// } +// }, +// ... +// ] +~~~ + +~~~ts +// Get the supported strategies by token and chain identifier +const supportedStrategiesByToken = await client.getStrategiesByToken('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +// [ +// { +// "ID": 19, +// "alias": "Default strategy for token YAM", +// "predicate": "YAM", +// "uri": "ipfs://bafybeicddxfktpcmbkvrflifbod6eeaizfab7l5ijggswnn5jwu3uhv4i4", +// "tokens": { +// "YAM": { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// } +// } +// }, +// { +// "ID": 37, +// "alias": "testStrategy_1699887257144", +// "predicate": "(YAM OR API3) AND 1INCH", +// "uri": "ipfs://bafybeic2gw6nb75ledp3jbz46rmdrnti33hgtlm5icfluxn5ol4enqps7i", +// "tokens": { +// "1INCH": { +// "ID": "0x111111111117dC0aa78b770fA6A738034120C302", +// "chainID": 1, +// "minBalance": "50", +// "chainAddress": "eth:0x111111111117dC0aa78b770fA6A738034120C302" +// }, +// "API3": { +// "ID": "0x0b38210ea11411557c13457D4dA7dC6ea731B88a", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x0b38210ea11411557c13457D4dA7dC6ea731B88a" +// }, +// "YAM": { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "chainID": 1, +// "minBalance": "10000", +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// } +// } +// }, +// ... +// ] +~~~ + +~~~ts +// Get a strategy on a given identifier +const strategy = await client.getStrategy(1); +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// } +~~~ + +~~~ts +// Get strategy estimation information for creating census +const size = await client.getStrategyEstimation(1); +// { +// "size": 5516, +// "timeToCreateCensus": 3296, +// "accuracy": 100 +// } +~~~ + +~~~ts +// Creates a new strategy by passing the alias, the predicate and the tokens information +const strategyId = await client.createStrategy('test_strategy', '(wANT OR ANT) AND USDC', { + "wANT": { + "ID": "0x1324", + "chainID": 1, + "minBalance": "10000" + }, + "ANT": { + "ID": "0x1324", + "chainID": 5, + }, + "USDC": { + "ID": "0x1324", + "chainID": 1, + "minBalance": "50" + }, +}); +console.log(strategyId) // strategy identifier +~~~ + +~~~ts +// Imports a strategy from IPFS by the given cid +const strategy = await client.importStrategy('bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea'); +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// } +~~~ + +~~~ts +// Validates a predicate for a strategy and returns the parsed predicate in JSON +const validatePredicate = await client.validatePredicate('1INCH AND (YAM OR API3)'); +// { +// "result": { +// "childs": { +// "operator": "AND", +// "tokens": [ +// { +// "childs": { +// "operator": "OR", +// "tokens": [ +// { +// "literal": "YAM" +// }, +// { +// "literal": "API3" +// } +// ] +// } +// }, +// { +// "literal": "1INCH" +// } +// ] +// } +// } +// } +~~~ + +~~~ts +// Gets the supported predicate operators +const operators = await client.getSupportedOperators(); +// [ +// { +// "description": "AND logical operator that returns the common token holders between symbols with fixed balance to 1", +// "tag": "AND" +// }, +// { +// "description": "AND:sum logical operator that returns the common token holders between symbols with the sum of their balances on both tokens", +// "tag": "AND:sum" +// }, +// { +// "description": "AND:mul logical operator that returns the common token holders between symbols with the multiplication of their balances on both tokens", +// "tag": "AND:mul" +// }, +// ... +// ] +~~~ + +#### Getting censuses information and creating them + +~~~ts +// Get the supported censuses by strategy identifier +const strategyID = 18; +const censusesByStrategy = await client.getCensuses(strategyID); +// [ +// { +// "ID": 18569955180, +// "strategyID": 18, +// "merkleRoot": "9b1ac0ed374a66b781a22ec5e1b1382324adc0759662e1e6f85fc87f5a23407e", +// "uri": "ipfs://bafybeihwz2mbkkphgs2ni5laymgtfokaskujg2qfqcvoxhkccbdqp6k7ly", +// "size": 14999, +// "weight": "81637958624197446065983341792", +// "anonymous": false +// }, +// { +// "ID": 18569991180, +// "strategyID": 18, +// "merkleRoot": "ab1c003b923c4fec0b24f84893ddda8835fd3990904dc64f06c1fc0eadef402f", +// "uri": "ipfs://bafybeig5jrzw7ayxb442evan4pwa4rfksznh3smyt4exyjkubet2u5ldjm", +// "size": 14999, +// "weight": "653103668993579568527866734336", +// "anonymous": false +// }, +// ... +// ] +~~~ + +~~~ts +// Get a census on a given identifier +const census = await client.getCensus(18569955180); +// { +// "ID": 18569955180, +// "strategyID": 18, +// "merkleRoot": "9b1ac0ed374a66b781a22ec5e1b1382324adc0759662e1e6f85fc87f5a23407e", +// "uri": "ipfs://bafybeihwz2mbkkphgs2ni5laymgtfokaskujg2qfqcvoxhkccbdqp6k7ly", +// "size": 14999, +// "weight": "1514939612264202552941935398517220938016694806267744586724593217517874", +// "anonymous": false +// } +~~~ + +~~~ts +// Creates a new census by passing the strategy identifier +const strategyID = 18; +const census = await client.createCensus(strategyID); +// { +// "ID": 18570184180, +// "strategyID": 18, +// "merkleRoot": "542166dd4757904449e71d5c21058597ab4179f040ee1f9e7dd29eec622ca5ed", +// "uri": "ipfs://bafybeifbhmytl6olebkdoas6uftj3ae5akutmji4io6k37ilzu5uli2nle", +// "size": 14999, +// "weight": "42801802051163230603042274301444096", +// "anonymous": false +// } +~~~ + +~~~ts +// Creates a new census by passing the token address, using the default strategy and returns +// an instance of `TokenCensus` which can be directly used as a census in the Vocdoni chain +const census = await client.createTokenCensus('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +console.log(typeof census); // TokenCensus +~~~ + ## Examples -You can find a [full featured CRA][example-cra] application with all the previous +You can find a [full featured vite][example-vite] application with all the previous steps in the [examples] folder. In that folder you'll also find a [es modules example][example-esm], creating and voting an election process. @@ -589,7 +1016,7 @@ This SDK is licensed under the [GNU Affero General Public License v3.0][license] [election-lifecycle-states]: https://developer.vocdoni.io/get-started/intro#election-lifecycle-states [election params interface]: https://github.com/vocdoni/vocdoni-sdk/blob/main/src/types/election/election.ts#23 [examples]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples -[example-cra]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/cra +[example-vite]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/vite-react-app [example-esm]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/esm [quadratic voting example]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/typescript/src/quadratic.ts [quadratic voting documentation]: https://developer.vocdoni.io/protocol/ballot#quadratic-voting diff --git a/docs/sdk/AccountAPI.mdx b/docs/sdk/AccountAPI.mdx index 2184b48fe..3033be8ab 100644 --- a/docs/sdk/AccountAPI.mdx +++ b/docs/sdk/AccountAPI.mdx @@ -12,7 +12,7 @@ class AccountAPI
Methods
-
infostatic
setInfostatic
transfersListstatic
electionsListstatic
+
liststatic
countstatic
infostatic
metadatastatic
setInfostatic
transfersListstatic
transfersCountstatic
electionsListstatic
## constructor @@ -27,6 +27,35 @@ new AccountAPI() Cannot be constructed. ## Methods +### list {#list} + +
+ static +
+ +Returns paginated list of accounts + +**Returns**: Promise<IAccountsListResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|page|number|✔️|0|The page number| + +### count {#count} + +
+ static +
+ +Returns the number of accounts + +**Returns**: Promise<IAccountsCountResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| + ### info {#info}
@@ -40,7 +69,22 @@ Fetches an Account information |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|address|string|||The one we want the info from| +|accountId|string|||The account we want the info from| + +### metadata {#metadata} + +
+ static +
+ +Fetches the account metadata + +**Returns**: Promise<[AccountMetadata](AccountMetadata)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|accountId|string|||The account we want the info from| ### setInfo {#setInfo} @@ -74,6 +118,21 @@ Returns paginated list of transfers for a specific account |accountId|string|||accountId to get transfers| |page|number|✔️|0|The page number| +### transfersCount {#transfersCount} + +
+ static +
+ +Returns the account's transfers count + +**Returns**: Promise<IAccountTransfersCountResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|accountId|string|||accountId to get the transfers count| + ### electionsList {#electionsList}
diff --git a/docs/sdk/AccountService.mdx b/docs/sdk/AccountService.mdx new file mode 100644 index 000000000..6ce9dab0d --- /dev/null +++ b/docs/sdk/AccountService.mdx @@ -0,0 +1,64 @@ +--- +custom_edit_url: null +--- + +```ts +class AccountService +``` + +
+ +
+ +
+
Methods
+
+
+ +## constructor +```ts +new AccountService(params) +``` + +
+ +
+ +Instantiate the election service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<AccountServiceParameters>|||The service parameters| + +## Methods + +### fetchAccountInfo {#fetchAccountInfo} + +
+ async +
+ +Fetches account information. + +**Returns**: Promise<[AccountData](AccountData)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|address|string|||The account address to fetch the information| + +### setInfo {#setInfo} + +
+ +
+ +Updates an account with information + +**Returns**: Promise<string> +- The transaction hash + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|tx|string|||The transaction for setting the account| +|metadata|string|||The account metadata| + diff --git a/docs/sdk/AnonymousService.mdx b/docs/sdk/AnonymousService.mdx new file mode 100644 index 000000000..6867050ce --- /dev/null +++ b/docs/sdk/AnonymousService.mdx @@ -0,0 +1,73 @@ +--- +custom_edit_url: null +--- + +```ts +class AnonymousService +``` + +
+ +
+ +
+
Methods
+
+
+ +## constructor +```ts +new AnonymousService(params) +``` + +
+ +
+ +Instantiate the anonymous service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<AnonymousServiceParameters>|||The service parameters| + +## Methods + +### checkCircuitsHashes {#checkCircuitsHashes} + +
+ +
+ +Checks circuit hashes + +**Returns**: ChainCircuits +- The checked circuit parameters + +### fetchCircuits {#fetchCircuits} + +
+ +
+ +Fetches circuits for anonymous voting + +**Returns**: Promise<ChainCircuits> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|circuits|Omit<ChainCircuits, ('zKeyData'\|'vKeyData'\|'wasmData')>|✔️||Additional options for custom circuits| + +### setCircuits {#setCircuits} + +
+ +
+ +Sets circuits for anonymous voting + +**Returns**: Promise<ChainCircuits> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|circuits|ChainCircuits|||Custom circuits| + diff --git a/docs/sdk/AnonymousVote.mdx b/docs/sdk/AnonymousVote.mdx new file mode 100644 index 000000000..753667aaf --- /dev/null +++ b/docs/sdk/AnonymousVote.mdx @@ -0,0 +1,29 @@ +--- +custom_edit_url: null +--- + +```ts +class AnonymousVote +``` + +
+ +
+ +## constructor +```ts +new AnonymousVote(votes, signature, password) +``` + +
+ +
+ +Constructs a csp vote + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|votes|Array<number \| TSBigIntKeyword>|||The list of votes values| +|signature|string|✔️||The signature of the payload| +|password|string|✔️|"0"|The password of the anonymous vote| + diff --git a/docs/sdk/ApprovalElection.mdx b/docs/sdk/ApprovalElection.mdx new file mode 100644 index 000000000..c900f4b31 --- /dev/null +++ b/docs/sdk/ApprovalElection.mdx @@ -0,0 +1,29 @@ +--- +custom_edit_url: null +--- + +```ts +class ApprovalElection +``` + +
+ +
+ +Represents an approval election + +## constructor +```ts +new ApprovalElection(params) +``` + +
+ +
+ +Constructs an approval election + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|IApprovalElectionParameters|||Approval election parameters| + diff --git a/docs/sdk/ArchivedCensus.mdx b/docs/sdk/ArchivedCensus.mdx new file mode 100644 index 000000000..6c7fcc8f5 --- /dev/null +++ b/docs/sdk/ArchivedCensus.mdx @@ -0,0 +1,33 @@ +--- +custom_edit_url: null +--- + +```ts +class ArchivedCensus +``` + +
+ +
+ +Represents an archived census + +## constructor +```ts +new ArchivedCensus(censusId, censusURI, type, size, weight) +``` + +
+ +
+ +Constructs an archived census + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||The id of the census| +|censusURI|string|✔️||The URI of the census| +|type|CensusType|✔️||The type of the census| +|size|number|✔️||The size of the census| +|weight|TSBigIntKeyword|✔️||The weight of the census| + diff --git a/docs/sdk/ArchivedElection.mdx b/docs/sdk/ArchivedElection.mdx new file mode 100644 index 000000000..63fe58396 --- /dev/null +++ b/docs/sdk/ArchivedElection.mdx @@ -0,0 +1,29 @@ +--- +custom_edit_url: null +--- + +```ts +class ArchivedElection +``` + +
+ +
+ +Represents a published election + +## constructor +```ts +new ArchivedElection(params) +``` + +
+ +
+ +Constructs an archived election + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|IPublishedElectionParameters|||Election parameters| + diff --git a/docs/sdk/BudgetElection.mdx b/docs/sdk/BudgetElection.mdx new file mode 100644 index 000000000..d41769a44 --- /dev/null +++ b/docs/sdk/BudgetElection.mdx @@ -0,0 +1,29 @@ +--- +custom_edit_url: null +--- + +```ts +class BudgetElection +``` + +
+ +
+ +Represents a budget election + +## constructor +```ts +new BudgetElection(params) +``` + +
+ +
+ +Constructs a budget election + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|IBudgetElectionParameters|||Budget election parameters| + diff --git a/docs/sdk/Census3CensusAPI.mdx b/docs/sdk/Census3CensusAPI.mdx index e06a572bc..d8875176d 100644 --- a/docs/sdk/Census3CensusAPI.mdx +++ b/docs/sdk/Census3CensusAPI.mdx @@ -12,7 +12,7 @@ class Census3CensusAPI
Methods
-
liststatic
censusstatic
createstatic
+
liststatic
censusstatic
queuestatic
createstatic
## constructor @@ -57,20 +57,35 @@ Returns the information of the census |url|string|||API endpoint URL| |id|number|||The identifier of the census| +### queue {#queue} + +
+ static +
+ +Returns the information of the census queue + +**Returns**: Promise<ICensus3CensusQueueResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|id|string|||The identifier of the census queue| + ### create {#create}
static
-Requests the creation of a new census with the strategy provided for the blockNumber. +Requests the creation of a new census with the strategy provided. -**Returns**: Promise<ICensus3CensusCreateResponse> -- promised ICensus3CensusCreateResponse +**Returns**: Promise<ICensus3QueueResponse> +- The queue identifier |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| |strategyId|number|||The strategy identifier| -|blockNumber|number|✔️||The number of the block| +|anonymous|boolean|✔️|false|If the census has to be anonymous| diff --git a/docs/sdk/Census3ServiceAPI.mdx b/docs/sdk/Census3ServiceAPI.mdx new file mode 100644 index 000000000..75ed43f57 --- /dev/null +++ b/docs/sdk/Census3ServiceAPI.mdx @@ -0,0 +1,43 @@ +--- +custom_edit_url: null +--- + +```ts +class Census3ServiceAPI +``` + +
+ +
+ +
+
Methods
+
infostatic
+
+ +## constructor +```ts +new Census3ServiceAPI() +``` + +
+ +
+ +Cannot be constructed. + +## Methods +### info {#info} + +
+ static +
+ +Fetches supported chains from the service + +**Returns**: Promise<ICensus3ServiceInfoResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| + diff --git a/docs/sdk/Census3StrategyAPI.mdx b/docs/sdk/Census3StrategyAPI.mdx index 32e24fedf..556af5787 100644 --- a/docs/sdk/Census3StrategyAPI.mdx +++ b/docs/sdk/Census3StrategyAPI.mdx @@ -12,7 +12,7 @@ class Census3StrategyAPI
Methods
-
liststatic
strategystatic
createstatic
+
## constructor @@ -35,13 +35,45 @@ Cannot be constructed. Fetches list of strategies +**Returns**: Promise<ICensus3StrategiesListResponsePaginated> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|pagination|Census3Pagination|✔️||Pagination options| + +### holders {#holders} + +
+ static +
+ +Fetches list of holders by strategy + +**Returns**: Promise<ICensus3StrategyHoldersResponsePaginated> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|id|number|||The identifier of the strategy| +|pagination|Census3Pagination|✔️||Pagination options| + +### listByToken {#listByToken} + +
+ static +
+ +Fetches list of strategies based on given token + **Returns**: Promise<ICensus3StrategiesListResponse> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|page|number|✔️|0|The page number| -|token|string|✔️||The token id or address| +|tokenId|string|||The identifier of the token| +|chainId|number|||The chain identifier of the token| +|externalId|string|✔️||The identifier used by external provider| ### strategy {#strategy} @@ -51,13 +83,77 @@ Fetches list of strategies Returns the information of the strategy -**Returns**: Promise<ICensus3StrategyResponse> +**Returns**: Promise<Census3Strategy> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| |id|number|||The identifier of the strategy| +### estimation {#estimation} + +
+ static +
+ +Returns the estimation of size and time (in milliseconds) to create the census generated for the provided strategy + +**Returns**: Promise<ICensus3QueueResponse> +- The queue identifier + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|id|number|||The identifier of the strategy| +|anonymous|boolean|✔️|false|If the estimation should be done for anonymous census| + +### estimationQueue {#estimationQueue} + +
+ static +
+ +Returns the information of the strategy estimation queue + +**Returns**: Promise<ICensus3StrategyEstimationQueueResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|strategyId|number|||The identifier of the strategy| +|queueId|string|||The identifier of the strategy estimation queue| + +### importQueue {#importQueue} + +
+ static +
+ +Returns the information of the strategy import queue + +**Returns**: Promise<ICensus3StrategyImportQueueResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|queueId|string|||The identifier of the strategy import queue| + +### import {#import} + +
+ static +
+ +Imports a strategy from IPFS from the given cid. + +**Returns**: Promise<ICensus3QueueResponse> +- The queue identifier + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|cid|string|||The cid of the IPFS where the strategy is stored| + ### create {#create}
@@ -67,11 +163,42 @@ Returns the information of the strategy Creates a new strategy based on the given token strategies and predicate. **Returns**: Promise<ICensus3StrategyCreateResponse> -- promised ICensus3StrategyCreateResponse +- The identifier of the created strategy + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|alias|string|||The alias of the strategy| +|predicate|string|||The predicate of the strategy| +|tokens|{[key: string]: Census3CreateStrategyToken}|||The token list for the strategy| + +### validatePredicate {#validatePredicate} + +
+ static +
+ +Validates a predicate. + +**Returns**: Promise<ICensus3ValidatePredicateResponse> +- Parsed version of the predicate + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|predicate|string|||The predicate of the strategy| + +### operators {#operators} + +
+ static +
+ +Returns the list of supported operators to build strategy predicates. + +**Returns**: Promise<ICensus3StrategiesOperatorsResponse> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|tokens|Array<ICensus3StrategyToken>|||The token list with strategies| -|strategy|string|||The stringified strategy (predicate)| diff --git a/docs/sdk/Census3TokenAPI.mdx b/docs/sdk/Census3TokenAPI.mdx index 387dadc71..2b72782cb 100644 --- a/docs/sdk/Census3TokenAPI.mdx +++ b/docs/sdk/Census3TokenAPI.mdx @@ -12,7 +12,7 @@ class Census3TokenAPI
Methods
-
liststatic
typesstatic
tokenstatic
createstatic
+
liststatic
typesstatic
tokenstatic
holderstatic
createstatic
## constructor @@ -35,11 +35,12 @@ Cannot be constructed. Fetches list of already added tokens -**Returns**: Promise<ICensus3TokenListResponse> +**Returns**: Promise<ICensus3TokenListResponsePaginated> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| +|pagination|Census3Pagination|✔️||Pagination options| ### types {#types} @@ -63,12 +64,33 @@ Fetches list of tokens types Fetch the full token information -**Returns**: Promise<ICensus3Token> +**Returns**: Promise<Census3Token> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|id|string|||The id of the token| +|tokenId|string|||The identifier of the token| +|chainId|number|||The chain identifier of the token| +|externalId|string|✔️||The identifier used by external provider| + +### holder {#holder} + +
+ static +
+ +Returns if the holder ID is already registered in the database as a holder of the token ID and chain ID provided. + +**Returns**: Promise<ICensus3TokenHolderResponse> +- The balance of holder + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|tokenId|string|||The identifier of the token| +|chainId|number|||The chain identifier of the token| +|holderId|string|||The identifier of the holder| +|externalId|string|✔️||The identifier used by external provider| ### create {#create} @@ -76,7 +98,7 @@ Fetch the full token information static
-Triggers a new scan for the provided token, starting from the defined block. +Triggers a new scan for the provided token. **Returns**: Promise<IFileCIDResponse> - promised IFileCIDResponse @@ -86,6 +108,7 @@ Triggers a new scan for the provided token, starting from the defined block. |url|string|||API endpoint URL| |id|string|||The token address| |type|string|||The type of the token| -|startBlock|number|||The start block| -|tag|Array<string>|✔️||The tags assigned for the token| +|chainId|number|||The chain id of the token| +|tags|Array<string>|✔️||The tags assigned for the token| +|externalId|string|✔️||The identifier used by external provider| diff --git a/docs/sdk/CensusAPI.mdx b/docs/sdk/CensusAPI.mdx index 21dcfb205..e57548651 100644 --- a/docs/sdk/CensusAPI.mdx +++ b/docs/sdk/CensusAPI.mdx @@ -12,7 +12,7 @@ class CensusAPI
Methods
-
createstatic
addstatic
publishstatic
proofstatic
sizestatic
weightstatic
+
createstatic
addstatic
publishstatic
proofstatic
exportstatic
importstatic
deletestatic
sizestatic
weightstatic
typestatic
## constructor @@ -94,6 +94,60 @@ Checks if the specified address is in the specified census |censusId|string|||The census ID of which we want the proof from| |key|string|||The address to be checked| +### export {#export} + +
+ static +
+ +Exports the given census identifier + +**Returns**: Promise<ICensusExportResponse> +- on success + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|authToken|string|||Authentication token| +|censusId|string|||The census ID we want to export| + +### import {#import} + +
+ static +
+ +Imports data into the given census identifier + +**Returns**: Promise<void> +- on success + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|authToken|string|||Authentication token| +|censusId|string|||The census ID we want to export| +|type|number|||The type of the census| +|rootHash|string|||The root hash of the census| +|data|string|||The census data to be imported| + +### delete {#delete} + +
+ static +
+ +Deletes the given census + +**Returns**: Promise<void> +- on success + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|authToken|string|||Authentication token| +|censusId|string|||The census ID we want to export| + ### size {#size}
@@ -107,7 +161,7 @@ Returns the size of a given census |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|censusId|string|||The census ID of which we want the proof from| +|censusId|string|||The census ID| ### weight {#weight} @@ -122,5 +176,20 @@ Returns the weight of a given census |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|censusId|string|||The census ID of which we want the proof from| +|censusId|string|||The census ID| + +### type {#type} + +
+ static +
+ +Returns the type of given census + +**Returns**: Promise<ICensusTypeResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|censusId|string|||The census ID| diff --git a/docs/sdk/CensusImportExport.mdx b/docs/sdk/CensusImportExport.mdx new file mode 100644 index 000000000..44d961f26 --- /dev/null +++ b/docs/sdk/CensusImportExport.mdx @@ -0,0 +1,15 @@ +--- +custom_edit_url: null +--- + +
+ +
+ +|PROPERTY|TYPE|DESCRIPTION| +|:---:|:---:|:---:| +|type|number|| +|rootHash|string|| +|data|string|| +|maxLevels|number|| + diff --git a/docs/sdk/OffchainCensusProof.mdx b/docs/sdk/CensusProof.mdx similarity index 85% rename from docs/sdk/OffchainCensusProof.mdx rename to docs/sdk/CensusProof.mdx index 5e4263e22..420823f9c 100644 --- a/docs/sdk/OffchainCensusProof.mdx +++ b/docs/sdk/CensusProof.mdx @@ -11,5 +11,4 @@ custom_edit_url: null |weight|string|| |proof|string|| |value|string|| -|type|CensusProofType|| diff --git a/docs/sdk/CensusService.mdx b/docs/sdk/CensusService.mdx new file mode 100644 index 000000000..447ff87b0 --- /dev/null +++ b/docs/sdk/CensusService.mdx @@ -0,0 +1,158 @@ +--- +custom_edit_url: null +--- + +```ts +class CensusService +``` + +
+ +
+ +
+
Methods
+ +
+ +## constructor +```ts +new CensusService(params) +``` + +
+ +
+ +Instantiate the census service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<CensusServiceParameters>|||The service parameters| + +## Methods + +### get {#get} + +
+ +
+ +Fetches the information of a given census. + +**Returns**: Promise<{size: number, weight: bigint, type: CensusType}> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||| + +### delete {#delete} + +
+ +
+ +Deletes the given census. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||| + +### fetchProof {#fetchProof} + +
+ async +
+ +Fetches proof that an address is part of the specified census. + +**Returns**: Promise<[CensusProof](CensusProof)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||Census we want to check the address against| +|key|string|||The address to be found| + +### publish {#publish} + +
+ +
+ +Publishes the given census identifier. + +**Returns**: Promise<ICensusPublishResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||The census identifier| + +### export {#export} + +
+ +
+ +Exports the given census identifier. + +**Returns**: Promise<[CensusImportExport](CensusImportExport)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||The census identifier| + +### import {#import} + +
+ +
+ +Imports data into the given census identifier. + +**Returns**: Promise<ICensusImportResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||The census identifier| +|data|[CensusImportExport](CensusImportExport)|||The census data| + +### createCensus {#createCensus} + +
+ +
+ +Publishes the given census. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|census|[PlainCensus](PlainCensus) \| [WeightedCensus](WeightedCensus)|||The census to be published.| + +### createCensusParallel {#createCensusParallel} + +
+ +
+ +Publishes the given census. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|census|[PlainCensus](PlainCensus) \| [WeightedCensus](WeightedCensus)|||The census to be published.| + +### fetchAccountToken {#fetchAccountToken} + +
+ +
+ +Fetches the specific account token auth and sets it to the current instance. + +**Returns**: Promise<void> + diff --git a/docs/sdk/ChainService.mdx b/docs/sdk/ChainService.mdx new file mode 100644 index 000000000..7799e21c4 --- /dev/null +++ b/docs/sdk/ChainService.mdx @@ -0,0 +1,115 @@ +--- +custom_edit_url: null +--- + +```ts +class ChainService +``` + +
+ +
+ +
+
Methods
+ +
+ +## constructor +```ts +new ChainService(params) +``` + +
+ +
+ +Instantiate the chain service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<ChainServiceParameters>|||The service parameters| + +## Methods + +### fetchChainData {#fetchChainData} + +
+ +
+ +Fetches blockchain information if needed. + +**Returns**: Promise<ChainData> + +### fetchChainCosts {#fetchChainCosts} + +
+ +
+ +Fetches blockchain costs information if needed. + +**Returns**: Promise<ChainCosts> + +### submitTx {#submitTx} + +
+ +
+ +Submits a transaction to the blockchain + +**Returns**: Promise<string> +- The transaction hash + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|payload|string|||The transaction data payload| + +### txInfo {#txInfo} + +
+ +
+ +Fetches information about a transaction from the blockchain. + +**Returns**: Promise<ChainTx> +- The chain transaction + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|txHash|string|||The transaction hash which we want to retrieve the info from| + +### dateToBlock {#dateToBlock} + +
+ +
+ +Returns the block number for a given date. + +**Returns**: Promise<number> +- The block number + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|date|Date|||The date which we want to retrieve the block number from| + +### waitForTransaction {#waitForTransaction} + +
+ +
+ +A convenience method to wait for a transaction to be executed. It will
loop trying to get the transaction information, and will retry every time
it fails. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|tx|string|||Transaction to wait for| +|wait|number|✔️||The delay in milliseconds between tries| +|attempts|attempts|✔️||The attempts to try before failing| + diff --git a/docs/sdk/CspService.mdx b/docs/sdk/CspService.mdx new file mode 100644 index 000000000..4b7e46540 --- /dev/null +++ b/docs/sdk/CspService.mdx @@ -0,0 +1,27 @@ +--- +custom_edit_url: null +--- + +```ts +class CspService +``` + +
+ +
+ +## constructor +```ts +new CspService(params) +``` + +
+ +
+ +Instantiate the CSP service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<CspServiceParameters>|||The service parameters| + diff --git a/docs/sdk/CspVote.mdx b/docs/sdk/CspVote.mdx index 7689080ca..b5500c85b 100644 --- a/docs/sdk/CspVote.mdx +++ b/docs/sdk/CspVote.mdx @@ -12,7 +12,7 @@ class CspVote ## constructor ```ts -new CspVote(votes, signature) +new CspVote(votes, signature, proof_type) ```
@@ -25,4 +25,5 @@ Constructs a csp vote |:---:|:---:|:---:|:---:|:---:| |votes|Array<number \| TSBigIntKeyword>|||The list of votes values| |signature|string|||The CSP signature| +|proof_type|CspProofType|✔️||The CSP proof type| diff --git a/docs/sdk/ElectionAPI.mdx b/docs/sdk/ElectionAPI.mdx index 8b28e723e..f5f42fa05 100644 --- a/docs/sdk/ElectionAPI.mdx +++ b/docs/sdk/ElectionAPI.mdx @@ -12,7 +12,7 @@ class ElectionAPI
Methods
-
infostatic
keysstatic
createstatic
votesCountstatic
votesListstatic
electionsListstatic
pricestatic
+
infostatic
keysstatic
createstatic
nextElectionIdstatic
votesCountstatic
votesListstatic
electionsListstatic
pricestatic
## constructor @@ -73,6 +73,23 @@ Creates a new election. |payload|string|||The set information info raw payload to be submitted to the chain| |metadata|string|||The base64 encoded metadata JSON object| +### nextElectionId {#nextElectionId} + +
+ static +
+ +Returns the next election id. + +**Returns**: Promise<IElectionNextIdResponse> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|organizationId|string|||The identifier of the organization| +|censusOrigin|number|||The census origin| +|envelopeType|IVoteMode|✔️||The envelope type| + ### votesCount {#votesCount}
@@ -137,7 +154,7 @@ Calculates the election price. |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| |maxCensusSize|number|||| -|electionBlocks|number|||| +|electionDuration|number|||| |encryptedVotes|boolean|||| |anonymousVotes|boolean|||| |maxVoteOverwrite|number|||| diff --git a/docs/sdk/ElectionCore.mdx b/docs/sdk/ElectionCore.mdx index 1a19b2518..ae90e7a73 100644 --- a/docs/sdk/ElectionCore.mdx +++ b/docs/sdk/ElectionCore.mdx @@ -10,11 +10,6 @@ class ElectionCore
- - ## constructor ```ts new ElectionCore() @@ -26,34 +21,3 @@ new ElectionCore() Cannot be constructed. -## Methods -### estimateDateAtBlock {#estimateDateAtBlock} - -
- static -
- -Returns the DateTime at which the given block number is expected to be mined - -**Returns**: Date - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|blockNumber|number|||The desired block number| -|chainData|ChainData|||The block status information from the chain to use for the estimation| - -### estimateBlockAtDateTime {#estimateBlockAtDateTime} - -
- static -
- -Returns the block number that is expected to be current at the given date and time - -**Returns**: number - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|dateTime|Date|||The desired date time| -|chainData|ChainData|||The block status information from the chain to use for the estimation| - diff --git a/docs/sdk/ElectionService.mdx b/docs/sdk/ElectionService.mdx new file mode 100644 index 000000000..8c2e1bcef --- /dev/null +++ b/docs/sdk/ElectionService.mdx @@ -0,0 +1,155 @@ +--- +custom_edit_url: null +--- + +```ts +class ElectionService +``` + +
+ +
+ + + +## constructor +```ts +new ElectionService(params) +``` + +
+ +
+ +Instantiate the election service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<ElectionServiceParameters>|||The service parameters| + +## Methods + +### fetchElection {#fetchElection} + +
+ async +
+ +Fetches info about an election. + +**Returns**: Promise<[UnpublishedElection](UnpublishedElection)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|electionId|string|||The id of the election| + +### create {#create} + +
+ +
+ +Creates a new election. + +**Returns**: Promise<ElectionCreatedInformation> +- The created election information + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|payload|string|||The set information info raw payload to be submitted to the chain| +|metadata|string|||The base64 encoded metadata JSON object| + +### nextElectionId {#nextElectionId} + +
+ +
+ +Returns the next election id. + +**Returns**: Promise<string> +- The next election identifier + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|address|string|||The address of the account| +|election|[UnpublishedElection](UnpublishedElection)|||The unpublished election| + +### getElectionSalt {#getElectionSalt} + +
+ +
+ +Returns an election salt for address + +**Returns**: Promise<string> +- The election salt + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|address|string|||The address of the account| +|electionCount|number|||The election count| + +### getNumericElectionId {#getNumericElectionId} + +
+ +
+ +Returns a numeric election identifier + +**Returns**: number +- The numeric identifier + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|electionId|string|||The identifier of the election| + +### keys {#keys} + +
+ +
+ +Fetches the encryption keys from the specified process. + +**Returns**: Promise<ElectionKeys> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|electionId|string|||The identifier of the election| + +### estimateElectionCost {#estimateElectionCost} + +
+ +
+ +Estimates the election cost + +**Returns**: Promise<number> +- The cost in tokens. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|election|[UnpublishedElection](UnpublishedElection)|||| + +### calculateElectionCost {#calculateElectionCost} + +
+ +
+ +Calculate the election cost + +**Returns**: Promise<number> +- The cost in tokens. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|election|[UnpublishedElection](UnpublishedElection)|||| + diff --git a/docs/sdk/FaucetAPI.mdx b/docs/sdk/FaucetAPI.mdx index fa81c3364..ec45a99d7 100644 --- a/docs/sdk/FaucetAPI.mdx +++ b/docs/sdk/FaucetAPI.mdx @@ -33,13 +33,12 @@ Cannot be constructed. static
-Calls the collect tokens method. Only works under development. +Calls the collect tokens method. **Returns**: Promise<IFaucetCollectResponse> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |url|string|||API endpoint URL| -|authToken|string|||Authentication token| |address|string|||Address to send the tokens to| diff --git a/docs/sdk/FaucetOptions.mdx b/docs/sdk/FaucetOptions.mdx index 13392ab58..a0ea7933d 100644 --- a/docs/sdk/FaucetOptions.mdx +++ b/docs/sdk/FaucetOptions.mdx @@ -10,7 +10,5 @@ Specify custom Faucet. |PROPERTY|TYPE|DESCRIPTION| |:---:|:---:|:---:| -|url|string|| -|auth_token|string \| null|| -|token_limit|number \| null|| +|token_limit|number|| diff --git a/docs/sdk/FaucetService.mdx b/docs/sdk/FaucetService.mdx new file mode 100644 index 000000000..7cb42aadd --- /dev/null +++ b/docs/sdk/FaucetService.mdx @@ -0,0 +1,63 @@ +--- +custom_edit_url: null +--- + +```ts +class FaucetService +``` + +
+ +
+ +
+
Methods
+ +
+ +## constructor +```ts +new FaucetService(params) +``` + +
+ +
+ +Instantiate the chain service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<FaucetServiceParameters>|||The service parameters| + +## Methods + +### fetchPayload {#fetchPayload} + +
+ +
+ +Fetches a faucet payload. Only for development. + +**Returns**: Promise<{string}> +- The encoded faucet package + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|address|string|||The address where to send the tokens| + +### parseFaucetPackage {#parseFaucetPackage} + +
+ +
+ +Parses a faucet package. + +**Returns**: [FaucetPackage](FaucetPackage) + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|faucetPackage|string|||| + diff --git a/docs/sdk/FileService.mdx b/docs/sdk/FileService.mdx new file mode 100644 index 000000000..f502ee26b --- /dev/null +++ b/docs/sdk/FileService.mdx @@ -0,0 +1,49 @@ +--- +custom_edit_url: null +--- + +```ts +class FileService +``` + +
+ +
+ +
+
Methods
+ +
+ +## constructor +```ts +new FileService(params) +``` + +
+ +
+ +Instantiate the election service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<FileServiceParameters>|||The service parameters| + +## Methods + +### calculateCID {#calculateCID} + +
+ +
+ +Fetches the CID expected for the specified data content. + +**Returns**: Promise<string> +- Resulting CID + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|data|string|||The data of which we want the CID of| + diff --git a/docs/sdk/MultiChoiceElection.mdx b/docs/sdk/MultiChoiceElection.mdx new file mode 100644 index 000000000..6215a1d82 --- /dev/null +++ b/docs/sdk/MultiChoiceElection.mdx @@ -0,0 +1,29 @@ +--- +custom_edit_url: null +--- + +```ts +class MultiChoiceElection +``` + +
+ +
+ +Represents a multi choice election + +## constructor +```ts +new MultiChoiceElection(params) +``` + +
+ +
+ +Constructs a multi choice election + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|IMultiChoiceElectionParameters|||Multi choice election parameters| + diff --git a/docs/sdk/Service.mdx b/docs/sdk/Service.mdx new file mode 100644 index 000000000..7fc3c80fe --- /dev/null +++ b/docs/sdk/Service.mdx @@ -0,0 +1,23 @@ +--- +custom_edit_url: null +--- + +```ts +class Service +``` + +
+ +
+ +## constructor +```ts +new Service() +``` + +
+ +
+ +Cannot be constructed. + diff --git a/docs/sdk/Signing.mdx b/docs/sdk/Signing.mdx index 225c2f1f8..e077f774a 100644 --- a/docs/sdk/Signing.mdx +++ b/docs/sdk/Signing.mdx @@ -39,8 +39,7 @@ Prefix and Sign a binary payload using the given Ethers wallet or signer. |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|messageBytes|Uint8Array|||| -|chainId|string|||The ID of the Vocdoni blockchain deployment for which the message is intended to| +|message|string|||| |walletOrSigner|Wallet \| Signer|||| ### signRaw {#signRaw} diff --git a/docs/sdk/TokenCensus.mdx b/docs/sdk/TokenCensus.mdx index 6ba0bc2a7..9c6018605 100644 --- a/docs/sdk/TokenCensus.mdx +++ b/docs/sdk/TokenCensus.mdx @@ -14,7 +14,7 @@ Represents a census3 census ## constructor ```ts -new TokenCensus(censusId, censusURI, token, size, weight) +new TokenCensus(censusId, censusURI, anonymous, token, size, weight) ```
@@ -27,6 +27,7 @@ Constructs a census3 census |:---:|:---:|:---:|:---:|:---:| |censusId|string|||The id of the census| |censusURI|string|||The URI of the census| +|anonymous|boolean|||If the census is anonymous| |token|Token|||The token of the census| |size|number|✔️||The size of the census| |weight|TSBigIntKeyword|✔️||The weight of the census| diff --git a/docs/sdk/TxWaitOptions.mdx b/docs/sdk/TxWaitOptions.mdx index d878df5b1..135ac1d26 100644 --- a/docs/sdk/TxWaitOptions.mdx +++ b/docs/sdk/TxWaitOptions.mdx @@ -10,6 +10,6 @@ Specify custom retry times and attempts when waiting for a transaction. |PROPERTY|TYPE|DESCRIPTION| |:---:|:---:|:---:| -|retry_time|number \| null|| -|attempts|number \| null|| +|retryTime|number|| +|attempts|number|| diff --git a/docs/sdk/VocdoniCensus3Client.mdx b/docs/sdk/VocdoniCensus3Client.mdx index 2c963c2ec..fa0ca070c 100644 --- a/docs/sdk/VocdoniCensus3Client.mdx +++ b/docs/sdk/VocdoniCensus3Client.mdx @@ -12,7 +12,7 @@ class VocdoniCensus3Client ## constructor @@ -38,11 +38,22 @@ Instantiate new VocdoniCensus3 client.

To instantiate the client just
-Returns a list of summarized tokens supported by the service +Returns a list of summary tokens supported by the service **Returns**: Promise<Array<TokenSummary>> - Token summary list +### getSupportedChains {#getSupportedChains} + +
+ +
+ +Returns a list of supported chain identifiers + +**Returns**: Promise<Array<SupportedChain>> +- Supported chain list + ### getSupportedTypes {#getSupportedTypes}
@@ -54,6 +65,17 @@ Returns a list of supported tokens type **Returns**: Promise<Array<string>> - Supported tokens type list +### getSupportedOperators {#getSupportedOperators} + +
+ +
+ +Returns a list of supported strategies operators + +**Returns**: Promise<Array<SupportedOperator>> +- Supported strategies operators list + ### getToken {#getToken}
@@ -68,6 +90,44 @@ Returns the full token information based on the id (address) |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |id|string|||The id (address) of the token| +|chainId|number|||The id of the chain| +|externalId|string|✔️||The identifier used by external provider| + +### isHolderInToken {#isHolderInToken} + +
+ +
+ +Returns if the holder ID is already registered in the database as a holder of the token. + +**Returns**: Promise<boolean> +- If the holder is in the token + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|tokenId|string|||The id (address) of the token| +|chainId|number|||The id of the chain| +|holderId|string|||The identifier of the holder| +|externalId|string|✔️||The identifier used by external provider| + +### tokenHolderBalance {#tokenHolderBalance} + +
+ +
+ +Returns the balance of the holder based on the token and chain + +**Returns**: Promise<bigint> +- The balance of the holder + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|tokenId|string|||The id (address) of the token| +|chainId|number|||The id of the chain| +|holderId|string|||The identifier of the holder| +|externalId|string|✔️||The identifier used by external provider| ### createToken {#createToken} @@ -83,38 +143,53 @@ Creates a new token to be tracked in the service |:---:|:---:|:---:|:---:|:---:| |address|string|||The address of the token| |type|string|||The type of the token| +|chainId|number|✔️|1|The chain id of the token| +|externalId|string|✔️|""|The identifier used by external provider| |tags|string|✔️|[]|The tag list to associate the token with| -|startBlock|string|✔️|0|The start block where to start scanning| -### getStrategiesList {#getStrategiesList} +### getStrategies {#getStrategies}
-Returns the strategies identifiers list +Returns the strategies -**Returns**: Promise<Array<number>> -- The list of strategies identifiers +**Returns**: Promise<Array<Census3Strategy>> +- The list of strategies + +### getStrategyHolders {#getStrategyHolders} + +
+ +
+ +Returns the strategy holders + +**Returns**: Promise<StrategyHolders> +- The list strategy holders |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|options|{page?: number, token?: string}|✔️||| +|id|number|||The id of the strategy| +|pagination|Census3Pagination|✔️|{pageSize: -1}|Pagination options| -### getStrategies {#getStrategies} +### getStrategiesByToken {#getStrategiesByToken}
-Returns the strategies list +Returns the strategies from the given token -**Returns**: Promise<Array<Strategy>> +**Returns**: Promise<Array<Census3Strategy>> - The list of strategies |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|options|{page?: number, token?: string}|✔️||| +|id|string|||The id (address) of the token| +|chainId|number|||The id of the chain| +|externalId|string|✔️||The identifier used by external provider| ### getStrategy {#getStrategy} @@ -131,6 +206,22 @@ Returns the information of the strategy based on the id |:---:|:---:|:---:|:---:|:---:| |id|number|||The id of the strategy| +### getStrategyEstimation {#getStrategyEstimation} + +
+ +
+ +Returns the estimation of size and time (in milliseconds) to create the census generated for the provided strategy + +**Returns**: Promise<Strategy> +- The strategy estimation + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|id|number|||The id of the strategy| +|anonymous|boolean|✔️|false|If the estimation should be done for anonymous census| + ### createStrategy {#createStrategy}
@@ -144,23 +235,39 @@ Creates a new strategy based on the given tokens and predicate |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|tokens|Array<{id: string, name: string, minBalance: string, method: string}>|||| -|strategy|string|||The strategy predicate| +|alias|string|||The alias of the strategy| +|predicate|string|||The predicate of the strategy| +|tokens|{[key: string]: StrategyToken}|||The token list for the strategy| -### getCensusesList {#getCensusesList} +### importStrategy {#importStrategy}
-Returns the census3 censuses identifiers list +Imports a strategy from IPFS from the given cid. -**Returns**: Promise<Array<number>> -- The list of census3 censuses identifiers +**Returns**: Promise<Strategy> +- The strategy information + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|cid|number|||The IPFS cid of the strategy to import| + +### validatePredicate {#validatePredicate} + +
+ +
+ +Validates a predicate + +**Returns**: Promise<ParsedPredicate> +- The parsed predicate |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|options|{strategyId?: number}|✔️||| +|predicate|string|||The predicate of the strategy| ### getCensuses {#getCensuses} @@ -168,14 +275,14 @@ Returns the census3 censuses identifiers list
-Returns the census3 censuses list +Returns the census3 censuses -**Returns**: Promise<Array<Census3Census>> +**Returns**: Promise<Array<number>> - The list of census3 censuses |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|options|{strategyId?: number}|✔️||| +|strategyId|string|||The strategy identifier| ### getCensus {#getCensus} @@ -200,13 +307,13 @@ Returns the census3 census based on the given identifier Creates the census based on the given strategy -**Returns**: Promise<number> -- The id of the census +**Returns**: Promise<Census3Census> +- The census information |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |strategyId|number|||The id of the strategy| -|blockNumber|number|✔️||The block number| +|anonymous|boolean|✔️|false|If the census has to be anonymous| ### createTokenCensus {#createTokenCensus} @@ -214,7 +321,7 @@ Creates the census based on the given strategy async
-Returns the actual census based on the given token +Returns the actual census based on the given token using the default strategy set **Returns**: Promise<[TokenCensus](TokenCensus)> - The token census @@ -222,4 +329,7 @@ Returns the actual census based on the given token |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |address|string|||The address of the token| +|chainId|number|||The id of the chain| +|anonymous|boolean|✔️|false|If the census has to be anonymous| +|externalId|string|✔️||The identifier used by external provider| diff --git a/docs/sdk/VocdoniSDKClient.mdx b/docs/sdk/VocdoniSDKClient.mdx index 9c698d349..99b1a4f1c 100644 --- a/docs/sdk/VocdoniSDKClient.mdx +++ b/docs/sdk/VocdoniSDKClient.mdx @@ -14,7 +14,7 @@ Main Vocdoni client object. It's a wrapper for all the methods in api, core
Methods
- +
## constructor @@ -60,65 +60,6 @@ Sets an election id. Required by other methods like submitVote or createElection |:---:|:---:|:---:|:---:|:---:| |electionId|string|||Election id string| -### fetchChainId {#fetchChainId} - -
- -
- -Fetches blockchain information if needed and returns the chain id. - -**Returns**: Promise<string> - -### fetchChainCosts {#fetchChainCosts} - -
- -
- -Fetches blockchain costs information if needed. - -**Returns**: Promise<ChainCosts> - -### checkCircuitsHashes {#checkCircuitsHashes} - -
- -
- -Checks circuit hashes - -**Returns**: ChainCircuits -- The checked circuit parameters - -### setCircuits {#setCircuits} - -
- -
- -Sets circuits for anonymous voting - -**Returns**: Promise<ChainCircuits> - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|circuits|ChainCircuits|||Custom circuits| - -### fetchCircuits {#fetchCircuits} - -
- -
- -Fetches circuits for anonymous voting - -**Returns**: Promise<ChainCircuits> - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|circuits|Omit<ChainCircuits, ('zKeyData'\|'vKeyData'\|'wasmData')>|✔️||Additional options for custom circuits| - ### fetchAccountInfo {#fetchAccountInfo}
@@ -127,60 +68,25 @@ Fetches circuits for anonymous voting Fetches account information. -**Returns**: Promise<[AccountData](AccountData)> +**Returns**: Promise<(AccountData\|ArchivedAccountData)> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |address|string|✔️||The account address to fetch the information| -### calculateCID {#calculateCID} - -
- -
- -Fetches the CID expected for the specified data content. - -**Returns**: Promise<string> -- Resulting CID - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|data|string|||The data of which we want the CID of| - -### fetchFaucetPayload {#fetchFaucetPayload} - -
- -
- -Fetches a faucet payload. Only for development. - -**Returns**: Promise<{string}> - -### parseFaucetPackage {#parseFaucetPackage} +### fetchAccount {#fetchAccount}
- + async
-Parses a faucet package. +Fetches account. -**Returns**: [FaucetPackage](FaucetPackage) +**Returns**: Promise<[AccountData](AccountData)> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|faucetPackage|string|||| - -### fetchAccountToken {#fetchAccountToken} - -
- -
- -Fetches the specific account token auth and sets it to the current instance. - -**Returns**: Promise<void> +|address|string|✔️||The account address to fetch the information| ### fetchElection {#fetchElection} @@ -190,58 +96,44 @@ Fetches the specific account token auth and sets it to the current instance. Fetches info about an election. -**Returns**: Promise<[UnpublishedElection](UnpublishedElection)> +**Returns**: Promise<(PublishedElection\|ArchivedElection)> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |electionId|string|✔️||The id of the election| -### waitForTransaction {#waitForTransaction} +### fetchProofForWallet {#fetchProofForWallet}
-A convenience method to wait for a transaction to be executed. It will
loop trying to get the transaction information, and will retry every time
it fails. - -**Returns**: Promise<void> - -|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| -|:---:|:---:|:---:|:---:|:---:| -|tx|string|||Transaction to wait for| -|wait|number|✔️||The delay in milliseconds between tries| -|attempts|attempts|✔️||The attempts to try before failing| - -### fetchProof {#fetchProof} - -
- async -
- Fetches proof that an address is part of the specified census. -**Returns**: Promise<[OffchainCensusProof](OffchainCensusProof)> +**Returns**: Promise<[CensusProof](CensusProof)> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|censusId|string|||Census we want to check the address against| -|key|string|||The address to be found| -|type|CensusProofType|||Type of census| +|censusId|string|||| +|wallet|Wallet \| Signer|||| -### fetchProofForWallet {#fetchProofForWallet} +### calcZKProofForWallet {#calcZKProofForWallet}
- + async
-Fetches proof that an address is part of the specified census. +Calculates ZK proof from given wallet. -**Returns**: Promise<[OffchainCensusProof](OffchainCensusProof)> +**Returns**: Promise<ZkProof> |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| |election|[PublishedElection](PublishedElection)|||| |wallet|Wallet \| Signer|||| +|signature|string|||| +|votePackage|Buffer|||| +|password|string|✔️|"0"|| ### createAccountInfo {#createAccountInfo} @@ -283,7 +175,7 @@ Updates an account with information |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|promAccountData|Promise<{tx: Uint8Array, metadata: string}>|||| +|promAccountData|Promise<{tx: Uint8Array, metadata: string, message: string}>|||| ### createAccount {#createAccount} @@ -299,55 +191,60 @@ Registers an account against vochain, so it can create new elections. |:---:|:---:|:---:|:---:|:---:| |options|Object|✔️||Additional
options, like extra information of the account, or the faucet package string| -### collectFaucetTokens {#collectFaucetTokens} +### sendTokens {#sendTokens}
-Calls the faucet to get new tokens. Only under development. +Send tokens from one account to another. -**Returns**: Promise<[AccountData](AccountData)> -- Account data information updated with new balance +**Returns**: Promise<void> -### createCensus {#createCensus} +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|options|SendTokensOptions|||Options for send tokens| + +### collectFaucetTokens {#collectFaucetTokens}
-Publishes the given census. +Calls the faucet to get new tokens. Only under development. -**Returns**: Promise<void> +**Returns**: Promise<[AccountData](AccountData)> +- Account data information updated with new balance |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|census|[PlainCensus](PlainCensus) \| [WeightedCensus](WeightedCensus)|||The census to be published.| +|faucetPackage|string|✔️||The faucet package| -### fetchCensusInfo {#fetchCensusInfo} +### createElection {#createElection}
- + async
-Fetches the information of a given census. +Creates a new voting election. -**Returns**: Promise<{size: number, weight: bigint}> +**Returns**: Promise<string> +- Resulting election id. |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|censusId|string|||| +|election|[UnpublishedElection](UnpublishedElection)|||The election object to be created.| -### createElection {#createElection} +### createElectionSteps {#createElectionSteps}
async
-Creates a new voting election. +Creates a new voting election by steps with async returns. -**Returns**: Promise<string> -- Resulting election id. +**Returns**: AsyncGenerator<ElectionCreationStepValue> +- The async step returns. |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| @@ -452,13 +349,12 @@ Checks if the user is in census. |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|electionId|string|✔️||The id of the election| -|key|Object|✔️||The key in the census to check| +|options|HasAlreadyVotedOptions|✔️||Options for is in census| ### hasAlreadyVoted {#hasAlreadyVoted}
- + async
Checks if the user has already voted @@ -468,7 +364,7 @@ Checks if the user has already voted |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|electionId|string|✔️||The id of the election| +|options|HasAlreadyVotedOptions|✔️||Options for has already voted| ### isAbleToVote {#isAbleToVote} @@ -482,7 +378,7 @@ Checks if the user is able to vote |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|electionId|string|✔️||The id of the election| +|options|IsAbleToVoteOptions|✔️||Options for is able to vote| ### votesLeftCount {#votesLeftCount} @@ -496,7 +392,7 @@ Checks how many times a user can submit their vote |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|electionId|string|✔️||The id of the election| +|options|VotesLeftCountOptions|✔️||Options for votes left count| ### submitVote {#submitVote} @@ -504,14 +400,29 @@ Checks how many times a user can submit their vote async
-Submits a vote to the current instance election id. +Submits a vote. + +**Returns**: Promise<string> +- Vote confirmation id. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|vote|[Vote](Vote) \| [CspVote](CspVote) \| [AnonymousVote](AnonymousVote)|||The vote (or votes) to be sent.| + +### submitVoteSteps {#submitVoteSteps} + +
+ async +
+ +Submits a vote by steps. **Returns**: Promise<string> - Vote confirmation id. |PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| |:---:|:---:|:---:|:---:|:---:| -|vote|[Vote](Vote) \| [CspVote](CspVote)|||The vote (or votes) to be sent.| +|vote|[Vote](Vote) \| [CspVote](CspVote) \| [AnonymousVote](AnonymousVote)|||The vote (or votes) to be sent.| ### generateRandomWallet {#generateRandomWallet} @@ -524,6 +435,97 @@ Assigns a random Wallet to the client and returns its private key. **Returns**: string - The private key. +### fetchProof {#fetchProof} + +
+ async +
+ +Fetches proof that an address is part of the specified census. + +**Returns**: Promise<[CensusProof](CensusProof)> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||Census we want to check the address against| +|key|string|||The address to be found| + +### createCensus {#createCensus} + +
+ +
+ +Publishes the given census. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|census|[PlainCensus](PlainCensus) \| [WeightedCensus](WeightedCensus)|||The census to be published.| + +### fetchCensusInfo {#fetchCensusInfo} + +
+ +
+ +Fetches the information of a given census. + +**Returns**: Promise<{size: number, weight: bigint}> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|censusId|string|||| + +### fetchCircuits {#fetchCircuits} + +
+ +
+ +Fetches circuits for anonymous voting + +**Returns**: Promise<ChainCircuits> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|circuits|Omit<ChainCircuits, ('zKeyData'\|'vKeyData'\|'wasmData')>|✔️||Additional options for custom circuits| + +### setCircuits {#setCircuits} + +
+ +
+ +Sets circuits for anonymous voting + +**Returns**: Promise<ChainCircuits> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|circuits|ChainCircuits|||Custom circuits| + +### fetchChainCosts {#fetchChainCosts} + +
+ +
+ +Fetches blockchain costs information if needed. + +**Returns**: Promise<ChainCosts> + +### fetchChainId {#fetchChainId} + +
+ +
+ +Fetches blockchain information if needed and returns the chain id. + +**Returns**: Promise<string> + ### estimateElectionCost {#estimateElectionCost}
@@ -554,3 +556,58 @@ Calculate the election cost |:---:|:---:|:---:|:---:|:---:| |election|[UnpublishedElection](UnpublishedElection)|||| +### calculateCID {#calculateCID} + +
+ +
+ +Fetches the CID expected for the specified data content. + +**Returns**: Promise<string> +- Resulting CID + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|data|string|||The data of which we want the CID of| + +### fetchFaucetPayload {#fetchFaucetPayload} + +
+ +
+ +Fetches a faucet payload. Only for development. + +**Returns**: Promise<{string}> + +### parseFaucetPackage {#parseFaucetPackage} + +
+ +
+ +Parses a faucet package. + +**Returns**: [FaucetPackage](FaucetPackage) + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|faucetPackage|string|||The encoded faucet package| + +### waitForTransaction {#waitForTransaction} + +
+ +
+ +A convenience method to wait for a transaction to be executed. It will
loop trying to get the transaction information, and will retry every time
it fails. + +**Returns**: Promise<void> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|tx|string|||Transaction to wait for| +|wait|number|✔️||The delay in milliseconds between tries| +|attempts|attempts|✔️||The attempts to try before failing| + diff --git a/docs/sdk/VoteCore.mdx b/docs/sdk/VoteCore.mdx index 5f3c26914..67839f578 100644 --- a/docs/sdk/VoteCore.mdx +++ b/docs/sdk/VoteCore.mdx @@ -41,5 +41,5 @@ Packages the given parameters into a proof that can be submitted to the Vochain |:---:|:---:|:---:|:---:|:---:| |electionId|string|||| |type|CensusType|||| -|censusProof|[OffchainCensusProof](OffchainCensusProof) \| [CspCensusProof](CspCensusProof)|||| +|censusProof|[CensusProof](CensusProof) \| [CspCensusProof](CspCensusProof) \| ZkProof|||| diff --git a/docs/sdk/VoteService.mdx b/docs/sdk/VoteService.mdx new file mode 100644 index 000000000..534147c89 --- /dev/null +++ b/docs/sdk/VoteService.mdx @@ -0,0 +1,62 @@ +--- +custom_edit_url: null +--- + +```ts +class VoteService +``` + +
+ +
+ +
+
Methods
+ +
+ +## constructor +```ts +new VoteService(params) +``` + +
+ +
+ +Instantiate the election service. + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|params|Partial<VoteServiceParameters>|||The service parameters| + +## Methods + +### info {#info} + +
+ +
+ +Get the vote information + +**Returns**: Promise<VoteInfo> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|voteId|string|||The identifier of the vote| + +### vote {#vote} + +
+ +
+ +Submit the vote to the chain + +**Returns**: Promise<VoteSubmit> + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|payload|string|||The base64 encoded vote transaction| + diff --git a/docs/sdk/ZkAPI.mdx b/docs/sdk/ZkAPI.mdx new file mode 100644 index 000000000..5bb9037aa --- /dev/null +++ b/docs/sdk/ZkAPI.mdx @@ -0,0 +1,61 @@ +--- +custom_edit_url: null +--- + +```ts +class ZkAPI +``` + +
+ +
+ +
+
Methods
+
proofstatic
sikstatic
+
+ +## constructor +```ts +new ZkAPI() +``` + +
+ +
+ +Cannot be constructed. + +## Methods +### proof {#proof} + +
+ static +
+ +Returns the ZK proof on given address + +**Returns**: Promise<IZkProofResponse> +- The ZK proof + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|key|string|||The address to be checked| + +### sik {#sik} + +
+ static +
+ +Returns the SIK on given address + +**Returns**: Promise<IZkSIKResponse> +- The ZK proof + +|PARAMETER|TYPE|OPTIONAL|DEFAULT|DESCRIPTION| +|:---:|:---:|:---:|:---:|:---:| +|url|string|||API endpoint URL| +|key|string|||The address to be checked| + diff --git a/docs/sdk/changelog.md b/docs/sdk/changelog.md index ee827758b..386516482 100644 --- a/docs/sdk/changelog.md +++ b/docs/sdk/changelog.md @@ -5,7 +5,230 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.7.5] - 2024-02-15 + +### Added + +- Added support for getting token holder balance in Census3 using `tokenHolderBalance`. +- Added support for getting token holders based on strategy using `getStrategyHolders`. + +### Fixed + +- Fixed `CensusOrigin` when election is using CSP census and anonymous. +- Fixed bad generation of `dist` bundles in previous version. + +## [0.7.4] - 2024-02-06 + +### Added + +- Added new `CspProofType` type when voting in a CSP based election to choose the encryption type. + +## [0.7.3] - 2024-01-23 + +### Added + +- Added new `ApprovalElection` election type for creating approval elections easily. + +### Fixed + +- Fixed `costExponent` to 1. +- Fixed error when election has no metadata. +- Fixed error with questions results for elections with no new type metadata. + +## [0.7.2] - 2024-01-17 + +### Added + +- Added new `MultiChoiceElection` election type for creating multi-choice elections easily. +- Added new `BudgetElection` election type for creating budget elections easily. + +### Fixed + +- Results in published elections are now correctly returned for each type of election. + +## [0.7.1] - 2024-01-11 + +### Changed + +- Supported tokens from Census3 using `getSupportedTokens()` returns now a token summary. +- Census3 `getStrategyEstimation` accepts `anonymous` flag and returns `accuracy` for anonymous censuses. + +### Fixed + +- Removed `nullifier` from vote package. +- Returning census from type `CspCensus` when election is for CSP. + +### Added + +- Added `ArchivedAccountData` for dealing with archived accounts and new `fetchAccount` function in client. +- Added `ErrFaucetAlreadyFunded` for faucet limit requests. +- Added `ErrElectionFinished` for doing actions when election is finished. +- Added `submitVoteSteps` for voting using async generator steps. + +## [0.7.0] - 2023-12-13 + +### Changed + +- Changed sha256 library from `@ethersproject/sha2` to `js-sha256` for web workers. +- Using API endpoint for estimating blocks from dates when creating an election. +- [**BREAKING**] Census3 `getStrategySize` function changed to `getStrategyEstimation` giving estimated time and size for the given strategy. + +## [0.6.1] - 2023-11-29 + +### Added + +- New anonymous function `hasRegisteredSIK` for checking if a user has registered a SIK. + +### Fixed + +- Removed outliers from block times for avoiding block estimation issues. + +## [0.6.0] - 2023-11-28 + +### Added + +- New election service functions `nextElectionId` and `getElectionSalt`. + +### Changed + +- [**BREAKING**] Refactored options for `isInCensus`, `hasAlreadyVoted`, `isAbleToVote` and `votesLeftCount`. +- [**BREAKING**] New options for `AnonymousVote` which enable to add the user's signature. +- [**BREAKING**] New internal anonymous flow when signature is given by the consumer. + +## [0.5.3] - 2023-11-28 + +### Added + +- New account methods supported for listing, counting and checking account transfers in `AccountAPI`. + +### Fixed + +- Archived elections without census URI are now accepted. + +### Changed + +- Faucet options don't require `token_limit` anymore. + +## [0.5.2] - 2023-11-16 + +### Fixed + +- Anonymous vote packages are no longer signed. + +## [0.5.1] - 2023-11-15 + +### Fixed + +- Missing exported election type `ArchivedElection`. +- Faucet errors correctly shown with message. + +## [0.5.0] - 2023-11-14 + +### Changed + +- [**BREAKING**] New full integration for Census3 v2, using tokens, strategies and censuses. + +## [0.4.3] - 2023-11-09 + +### Added + +- Support for archived elections with new election type `ArchivedElection` and with new census with type `ArchivedCensus`. + +## [0.4.2] - 2023-11-06 + +### Changed + +- Removed faucet path from default URLs. +- Updated `@vocdoni/proto` dependency to `1.15.4`. + +### Added + +- Import, export and delete census functionality in census service. +- Added new election parameter `temporarySecretIdentity` for deleting temporary SIKs once election is finished. + +### Fixed + +- Fixed `ffjavascript` dependency to `0.2.59`. + +## [0.4.1] - 2023-10-24 + +### Changed + +- Modified `dev`, `stg` and `prod` default URLs for all services. +- Upgraded to new faucet. + +## [0.4.0] - 2023-10-10 + +### Changed + +- [**BREAKING**] New signatures for chain transactions. + +## [0.3.2] - 2023-10-10 + +### Added + +- Added support for uploading big censuses in chunks. + +### Fixed + +- Added `assert` as embedded in rollup configuration. + +## [0.3.1] - 2023-09-20 + +### Added + +- New `createElectionSteps` function in client for using async generators and control creation flow. +- New `sendTokens` function in client for transferring tokens between accounts. + +### Changed + +- New user-friendly text for SIK payload signing. + +### Fixed + +- Added `ethers` as embedded in rollup configuration for `circomlibjs` dependencies. + +## [0.3.0] - 2023-09-13 + +### Fixed + +- Ensuring proof `value` handled as hex for anonymous circuits inputs. + +### Changed + +- [**BREAKING**] Removed some (probably not used) client properties for future refactor. +- Added services as mid-layer between pure SDK client and API wrappers. + +### Added + +- Census3 supported chains information. + +## [0.2.0] - 2023-09-04 + +### Fixed + +- `dotobject` helper returns null when key is not found. + +### Changed + +- `collectFaucetTokens` function accepts raw faucet package payload. + +### Added + +- Census3 error typings. +- [**BREAKING**] Census3 anonymous censuses. + +## [0.1.1] - 2023-08-14 + +### Fixed + +- Added missing dependency `readable-stream`. + +## [0.1.0] - 2023-08-11 + +### Added + +- [**BREAKING**] Anonymous integration ### Fixed @@ -227,6 +450,27 @@ which extend from the abstract `Election` class. - First unstable version of the SDK for testing purposes +[0.7.4]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.7.4 +[0.7.3]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.7.3 +[0.7.2]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.7.2 +[0.7.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.7.1 +[0.7.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.7.0 +[0.6.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.6.1 +[0.6.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.6.0 +[0.5.3]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.5.3 +[0.5.2]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.5.2 +[0.5.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.5.1 +[0.5.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.5.0 +[0.4.3]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.4.3 +[0.4.2]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.4.2 +[0.4.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.4.1 +[0.4.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.4.0 +[0.3.2]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.3.2 +[0.3.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.3.1 +[0.3.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.3.0 +[0.2.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.2.0 +[0.1.1]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.1.1 +[0.1.0]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.1.0 [0.0.18]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.0.18 [0.0.17]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.0.17 [0.0.16]: https://github.com/vocdoni/vocdoni-sdk/releases/tag/v0.0.16 diff --git a/docs/sdk/sdk.md b/docs/sdk/sdk.md index 3769240c6..de25da8d8 100644 --- a/docs/sdk/sdk.md +++ b/docs/sdk/sdk.md @@ -1,3 +1,18 @@ +

+ +

+ +
+ +![npm](https://img.shields.io/npm/v/%40vocdoni%2Fsdk) +![GitHub commit activity (main)](https://img.shields.io/github/commit-activity/m/vocdoni/vocdoni-sdk) +[![Example workflow](https://github.com/vocdoni/vocdoni-sdk/actions/workflows/examples.yml/badge.svg)](https://vocdoni.github.io/vocdoni-sdk/) +![Main workflow](https://github.com/vocdoni/vocdoni-sdk/actions/workflows/main.yml/badge.svg) +[![Join Discord](https://img.shields.io/badge/discord-join%20chat-blue.svg)](https://discord.gg/xFTh8Np2ga) +[![Twitter Follow](https://img.shields.io/twitter/follow/vocdoni.svg?style=social&label=Follow)](https://twitter.com/vocdoni) + +
+ # Vocdoni SDK The Vocdoni SDK is a convenient way to interact with the Vocdoni Protocol @@ -547,9 +562,421 @@ const vote = client.cspVote(new Vote([index % 2]), signature); const voteId = await client.submitVote(vote); ~~~ +## Census3 + +### What is Census3? + +Census3 is an API service to create censuses for elections with holders of a single token or a combination of them. +The service creates a list of holder addresses and balances and keeps it updated in real time, for every registered token. +Then, it allows creating a merkle tree census (compatible with [Vocdoni](https://vocdoni.io/)) with those holders, using their balances as vote weights. + +More information about Census3 can be found [here](https://github.com/vocdoni/census3). + +### Using Census3 + +The SDK comes with an implementation of the [Census3 API](https://github.com/vocdoni/census3/blob/main/api/README.md). + +#### Creating a Census3 client + +~~~ts +const client = new VocdoniCensus3Client({ + env: EnvOptions.DEV // dev environment +}) +~~~ + +#### Getting basic service information + +~~~ts +// Get the supported chains +const supportedChains = await client.getSupportedChains(); +// [ +// { +// "chainID": 1, +// "shortName": "eth", +// "name": "Ethereum Mainnet" +// }, +// { +// "chainID": 5, +// "shortName": "gor", +// "name": "Goerli" +// }, +// { +// "chainID": 137, +// "shortName": "matic", +// "name": "Polygon Mainnet" +// }, +// { +// "chainID": 80001, +// "shortName": "maticmum", +// "name": "Mumbai" +// } +// ] +~~~ + +~~~ts +// Get the supported token types +const supportedTypes = await client.getSupportedTypes(); +// ["erc20", "erc777", "poap", "unknown", "erc721burned", "erc1155", "nation3", "want", "erc721"] +~~~ + +#### Getting tokens information and creating them + +~~~ts +// Get the supported tokens +const supportedTokens = await client.getSupportedTokens(); +// [ +// { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 10886913, +// "symbol": "YAM", +// "totalSupply": "", +// "name": "YAM", +// "status": { +// "atBlock": 18565762, +// "synced": true, +// "progress": 100 +// }, +// "size": 14999, +// "defaultStrategy": 19, +// "chainID": 1, +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// }, +// { +// "ID": "0x0b38210ea11411557c13457D4dA7dC6ea731B88a", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 11203771, +// "symbol": "API3", +// "totalSupply": "", +// "name": "API3", +// "status": { +// "atBlock": 18565763, +// "synced": true, +// "progress": 100 +// }, +// "size": 51178, +// "defaultStrategy": 8, +// "chainID": 1, +// "chainAddress": "eth:0x0b38210ea11411557c13457D4dA7dC6ea731B88a" +// }, +// ... +// ] +~~~ + +~~~ts +// Get a token by its ID (address) and chain identifier +const token = await client.getToken('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +// { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "type": "erc20", +// "decimals": 18, +// "startBlock": 10886913, +// "symbol": "YAM", +// "totalSupply": "15164231312592159866595366", +// "name": "YAM", +// "status": { +// "atBlock": 18565783, +// "synced": true, +// "progress": 100 +// }, +// "size": 14999, +// "defaultStrategy": 19, +// "chainID": 1, +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "tags": [] +// } +~~~ + +~~~ts +// Check if a holder is registered for a given token +const token = await client.isHolderInToken( + '0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', + 1, + '0x111000000000000000000000000000000000dEaD' +); +// false +~~~ + +~~~ts +// Creates a new token by passing the address, the type and the chain identifier +const token = await client.createToken('0xa117000000f279d81a1d3cc75430faa017fa5a2e', 'erc20', 1); +~~~ + +#### Getting strategies information and creating them + +~~~ts +// Get the supported strategies +const supportedStrategies = await client.getStrategies(); +// [ +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// }, +// { +// "ID": 2, +// "alias": "Default strategy for token UNI", +// "predicate": "UNI", +// "uri": "ipfs://bafybeiesxbsbvp2agcuolezec6hvimntqdg3w43xs62mecdj2fyeh5anxu", +// "tokens": { +// "UNI": { +// "ID": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984" +// } +// } +// }, +// ... +// ] +~~~ + +~~~ts +// Get the supported strategies by token and chain identifier +const supportedStrategiesByToken = await client.getStrategiesByToken('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +// [ +// { +// "ID": 19, +// "alias": "Default strategy for token YAM", +// "predicate": "YAM", +// "uri": "ipfs://bafybeicddxfktpcmbkvrflifbod6eeaizfab7l5ijggswnn5jwu3uhv4i4", +// "tokens": { +// "YAM": { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// } +// } +// }, +// { +// "ID": 37, +// "alias": "testStrategy_1699887257144", +// "predicate": "(YAM OR API3) AND 1INCH", +// "uri": "ipfs://bafybeic2gw6nb75ledp3jbz46rmdrnti33hgtlm5icfluxn5ol4enqps7i", +// "tokens": { +// "1INCH": { +// "ID": "0x111111111117dC0aa78b770fA6A738034120C302", +// "chainID": 1, +// "minBalance": "50", +// "chainAddress": "eth:0x111111111117dC0aa78b770fA6A738034120C302" +// }, +// "API3": { +// "ID": "0x0b38210ea11411557c13457D4dA7dC6ea731B88a", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0x0b38210ea11411557c13457D4dA7dC6ea731B88a" +// }, +// "YAM": { +// "ID": "0x0AaCfbeC6a24756c20D41914F2caba817C0d8521", +// "chainID": 1, +// "minBalance": "10000", +// "chainAddress": "eth:0x0AaCfbeC6a24756c20D41914F2caba817C0d8521" +// } +// } +// }, +// ... +// ] +~~~ + +~~~ts +// Get a strategy on a given identifier +const strategy = await client.getStrategy(1); +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// } +~~~ + +~~~ts +// Get strategy estimation information for creating census +const size = await client.getStrategyEstimation(1); +// { +// "size": 5516, +// "timeToCreateCensus": 3296, +// "accuracy": 100 +// } +~~~ + +~~~ts +// Creates a new strategy by passing the alias, the predicate and the tokens information +const strategyId = await client.createStrategy('test_strategy', '(wANT OR ANT) AND USDC', { + "wANT": { + "ID": "0x1324", + "chainID": 1, + "minBalance": "10000" + }, + "ANT": { + "ID": "0x1324", + "chainID": 5, + }, + "USDC": { + "ID": "0x1324", + "chainID": 1, + "minBalance": "50" + }, +}); +console.log(strategyId) // strategy identifier +~~~ + +~~~ts +// Imports a strategy from IPFS by the given cid +const strategy = await client.importStrategy('bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea'); +// { +// "ID": 1, +// "alias": "Default strategy for token CRV", +// "predicate": "CRV", +// "uri": "ipfs://bafybeicjqjklqpumewpaue6weg47byz6fwmbg6ozief3w2pgqx7zlwl5ea", +// "tokens": { +// "CRV": { +// "ID": "0xD533a949740bb3306d119CC777fa900bA034cd52", +// "chainID": 1, +// "minBalance": "0", +// "chainAddress": "eth:0xD533a949740bb3306d119CC777fa900bA034cd52" +// } +// } +// } +~~~ + +~~~ts +// Validates a predicate for a strategy and returns the parsed predicate in JSON +const validatePredicate = await client.validatePredicate('1INCH AND (YAM OR API3)'); +// { +// "result": { +// "childs": { +// "operator": "AND", +// "tokens": [ +// { +// "childs": { +// "operator": "OR", +// "tokens": [ +// { +// "literal": "YAM" +// }, +// { +// "literal": "API3" +// } +// ] +// } +// }, +// { +// "literal": "1INCH" +// } +// ] +// } +// } +// } +~~~ + +~~~ts +// Gets the supported predicate operators +const operators = await client.getSupportedOperators(); +// [ +// { +// "description": "AND logical operator that returns the common token holders between symbols with fixed balance to 1", +// "tag": "AND" +// }, +// { +// "description": "AND:sum logical operator that returns the common token holders between symbols with the sum of their balances on both tokens", +// "tag": "AND:sum" +// }, +// { +// "description": "AND:mul logical operator that returns the common token holders between symbols with the multiplication of their balances on both tokens", +// "tag": "AND:mul" +// }, +// ... +// ] +~~~ + +#### Getting censuses information and creating them + +~~~ts +// Get the supported censuses by strategy identifier +const strategyID = 18; +const censusesByStrategy = await client.getCensuses(strategyID); +// [ +// { +// "ID": 18569955180, +// "strategyID": 18, +// "merkleRoot": "9b1ac0ed374a66b781a22ec5e1b1382324adc0759662e1e6f85fc87f5a23407e", +// "uri": "ipfs://bafybeihwz2mbkkphgs2ni5laymgtfokaskujg2qfqcvoxhkccbdqp6k7ly", +// "size": 14999, +// "weight": "81637958624197446065983341792", +// "anonymous": false +// }, +// { +// "ID": 18569991180, +// "strategyID": 18, +// "merkleRoot": "ab1c003b923c4fec0b24f84893ddda8835fd3990904dc64f06c1fc0eadef402f", +// "uri": "ipfs://bafybeig5jrzw7ayxb442evan4pwa4rfksznh3smyt4exyjkubet2u5ldjm", +// "size": 14999, +// "weight": "653103668993579568527866734336", +// "anonymous": false +// }, +// ... +// ] +~~~ + +~~~ts +// Get a census on a given identifier +const census = await client.getCensus(18569955180); +// { +// "ID": 18569955180, +// "strategyID": 18, +// "merkleRoot": "9b1ac0ed374a66b781a22ec5e1b1382324adc0759662e1e6f85fc87f5a23407e", +// "uri": "ipfs://bafybeihwz2mbkkphgs2ni5laymgtfokaskujg2qfqcvoxhkccbdqp6k7ly", +// "size": 14999, +// "weight": "1514939612264202552941935398517220938016694806267744586724593217517874", +// "anonymous": false +// } +~~~ + +~~~ts +// Creates a new census by passing the strategy identifier +const strategyID = 18; +const census = await client.createCensus(strategyID); +// { +// "ID": 18570184180, +// "strategyID": 18, +// "merkleRoot": "542166dd4757904449e71d5c21058597ab4179f040ee1f9e7dd29eec622ca5ed", +// "uri": "ipfs://bafybeifbhmytl6olebkdoas6uftj3ae5akutmji4io6k37ilzu5uli2nle", +// "size": 14999, +// "weight": "42801802051163230603042274301444096", +// "anonymous": false +// } +~~~ + +~~~ts +// Creates a new census by passing the token address, using the default strategy and returns +// an instance of `TokenCensus` which can be directly used as a census in the Vocdoni chain +const census = await client.createTokenCensus('0x0AaCfbeC6a24756c20D41914F2caba817C0d8521', 1); +console.log(typeof census); // TokenCensus +~~~ + ## Examples -You can find a [full featured CRA][example-cra] application with all the previous +You can find a [full featured vite][example-vite] application with all the previous steps in the [examples] folder. In that folder you'll also find a [es modules example][example-esm], creating and voting an election process. @@ -589,7 +1016,7 @@ This SDK is licensed under the [GNU Affero General Public License v3.0][license] [election-lifecycle-states]: https://developer.vocdoni.io/get-started/intro#election-lifecycle-states [election params interface]: https://github.com/vocdoni/vocdoni-sdk/blob/main/src/types/election/election.ts#23 [examples]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples -[example-cra]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/cra +[example-vite]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/vite-react-app [example-esm]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/esm [quadratic voting example]: https://github.com/vocdoni/vocdoni-sdk/blob/main/examples/typescript/src/quadratic.ts [quadratic voting documentation]: https://developer.vocdoni.io/protocol/ballot#quadratic-voting diff --git a/docs/sdk/sidebars-api.js b/docs/sdk/sidebars-api.js index 3f7de8ea3..c0cea9983 100644 --- a/docs/sdk/sidebars-api.js +++ b/docs/sdk/sidebars-api.js @@ -9,6 +9,7 @@ module.exports = { "sdk/CensusAPI", "sdk/Census3API", "sdk/Census3CensusAPI", + "sdk/Census3ServiceAPI", "sdk/Census3StrategyAPI", "sdk/Census3TokenAPI", "sdk/ChainAPI", @@ -18,13 +19,25 @@ module.exports = { "sdk/FileAPI", "sdk/VoteAPI", "sdk/WalletAPI", + "sdk/ZkAPI", "sdk/VocdoniCensus3Client", "sdk/VocdoniSDKClient", "sdk/AccountCore", "sdk/ElectionCore", "sdk/TransactionCore", "sdk/VoteCore", + "sdk/AccountService", + "sdk/AnonymousService", + "sdk/CensusService", + "sdk/ChainService", + "sdk/CspService", + "sdk/ElectionService", + "sdk/FaucetService", + "sdk/FileService", + "sdk/Service", + "sdk/VoteService", "sdk/Account", + "sdk/ArchivedCensus", "sdk/Census", "sdk/TokenCensus", "sdk/CspCensus", @@ -32,10 +45,15 @@ module.exports = { "sdk/PlainCensus", "sdk/PublishedCensus", "sdk/WeightedCensus", + "sdk/ApprovalElection", + "sdk/ArchivedElection", + "sdk/BudgetElection", "sdk/Election", "sdk/InvalidElection", + "sdk/MultiChoiceElection", "sdk/PublishedElection", "sdk/UnpublishedElection", + "sdk/AnonymousVote", "sdk/CspVote", "sdk/Vote", "sdk/Asymmetric", @@ -53,13 +71,14 @@ module.exports = { "type": "category", "label": "Typedef", "items": [ + "sdk/TxWaitOptions", + "sdk/ClientOptions", "sdk/AccountData", - "sdk/OffchainCensusProof", + "sdk/CensusProof", + "sdk/CensusImportExport", "sdk/CspCensusProof", - "sdk/FaucetPackage", "sdk/FaucetOptions", - "sdk/TxWaitOptions", - "sdk/ClientOptions" + "sdk/FaucetPackage" ] }, {