Merge pull request #634 from multiversx/TOOL-639-add-governance-in-docs

Add governance documantation and expose governance via entrypoints

Author: danielailie

cookbook/cookbook.md

@@ -208,7 +208,7 @@ When manually instantiating a network provider, you can provide a configuration
 }
 ```
 
-A full list of available methods for `ApiNetworkProvider` can be found [here](https://multiversx.github.io/mx-sdk-js-core/v14/classes/ApiNetworkProvider.html).
+Here you can find a full list of available methods for [`ApiNetworkProvider`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/ApiNetworkProvider.html).
 
 Both `ApiNetworkProvider` and `ProxyNetworkProvider` implement a common interface, which can be found [here](https://multiversx.github.io/mx-sdk-js-core/v14/interfaces/INetworkProvider.html). This allows them to be used interchangeably.
 
@@ -1749,8 +1749,8 @@ For scripts or quick network interactions, we recommend using the controller. Ho
 
 These are just a few examples of what you can do using the token management controller or factory. For a complete list of supported methods, please refer to the autogenerated documentation:
 
-- [TokenManagementController](https://multiversx.github.io/mx-sdk-js-core/v14/classes/TokenManagementController.html)
-- [TokenManagementTransactionsFactory](https://multiversx.github.io/mx-sdk-js-core/v14/classes/TokenManagementTransactionsFactory.html)
+- [`TokenManagementController`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/TokenManagementController.html)
+- [`TokenManagementTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/TokenManagementTransactionsFactory.html)
 
 ### Account management
 
@@ -1997,8 +1997,8 @@ In this section, we'll cover how to:
 - Undelegate and withdraw funds
 
 These operations can be performed using both the controller and the **factory**. For a complete list of supported methods, please refer to the autogenerated documentation:
-- [DelegationController](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationController.html)
-- [DelegationTransactionsFactory](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationTransactionsFactory.html)
+- [`DelegationController`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationController.html)
+- [`DelegationTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationTransactionsFactory.html)
 
 #### Creating a New Delegation Contract Using the Controller
 ```js
@@ -2613,6 +2613,172 @@ Flow for Creating Guarded Relayed Transactions:
 4. Then, the guardian signs.
 5. Finally, the relayer signs before broadcasting.
 
+### Governance
+
+We can create transactions for creating a new governance proposal, vote for a proposal or query the governance contract.
+
+These operations can be performed using both the **controller** and the **factory**. For a complete list of supported methods, please refer to the autogenerated documentation:
+- [`GovernanceController`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/GovernanceController.html)
+- [`GovernanceTransactionsFactory`](https://multiversx.github.io/mx-sdk-js-core/v14/classes/GovernanceTransactionsFactory.html)
+
+#### Creating a new proposal using the controller
+```js
+{
+    // create the entrypoint and the governance controller
+    const entrypoint = new DevnetEntrypoint();
+    const controller = entrypoint.createGovernanceController();
+
+    const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+    const alice = await Account.newFromPem(filePath);
+
+    // fetch the nonce of the network
+    alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+    const commitHash = "1db734c0315f9ec422b88f679ccfe3e0197b9d67";
+
+    const transaction = await controller.createTransactionForNewProposal(alice, alice.getNonceThenIncrement(), {
+        commitHash: commitHash,
+        startVoteEpoch: 10,
+        endVoteEpoch: 15,
+        nativeTokenAmount: 500_000000000000000000n,
+    });
+
+    // sending the transaction
+    const txHash = await entrypoint.sendTransaction(transaction);
+
+    // wait for transaction completion, extract proposal's details
+    const outcome = await controller.awaitCompletedProposeProposal(txHash);
+
+    const proposalNonce = outcome[0].proposalNonce;
+    const proposalCommitHash = outcome[0].commitHash;
+    const proposalStartVoteEpoch = outcome[0].startVoteEpoch;
+    const proposalEndVoteEpoch = outcome[0].endVoteEpoch;
+}
+```
+
+#### Creating a new proposal using the factory
+```js
+{
+    // create the entrypoint and the governance factory
+    const entrypoint = new DevnetEntrypoint();
+    const factory = entrypoint.createGovernanceTransactionsFactory();
+
+    const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+    const alice = await Account.newFromPem(filePath);
+
+    const commitHash = "1db734c0315f9ec422b88f679ccfe3e0197b9d67";
+
+    const transaction = factory.createTransactionForNewProposal(alice.address, {
+        commitHash: commitHash,
+        startVoteEpoch: 10,
+        endVoteEpoch: 15,
+        nativeTokenAmount: 500_000000000000000000n,
+    });
+    // fetch the nonce of the network
+    alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+    // set the nonce
+    transaction.nonce = alice.getNonceThenIncrement();
+
+    // sign the transaction
+    transaction.signature = await alice.signTransaction(transaction);
+
+    // sending the transaction
+    const txHash = await entrypoint.sendTransaction(transaction);
+
+    // waits until the transaction is processed and fetches it from the network
+    const transactionOnNetwork = await entrypoint.awaitCompletedTransaction(txHash);
+
+    const parser = new GovernanceTransactionsOutcomeParser({});
+    const outcome = parser.parseNewProposal(transactionOnNetwork);
+    const proposalNonce = outcome[0].proposalNonce;
+    const proposalCommitHash = outcome[0].commitHash;
+    const proposalStartVoteEpoch = outcome[0].startVoteEpoch;
+    const proposalEndVoteEpoch = outcome[0].endVoteEpoch;
+}
+```
+
+#### Vote for a proposal using the controller
+
+```js
+{
+    // create the entrypoint and the governance controller
+    const entrypoint = new DevnetEntrypoint();
+    const controller = entrypoint.createGovernanceController();
+
+    const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+    const alice = await Account.newFromPem(filePath);
+
+    // fetch the nonce of the network
+    alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+    const transaction = await controller.createTransactionForVoting(alice, alice.getNonceThenIncrement(), {
+        proposalNonce: 1,
+        vote: Vote.YES,
+    });
+
+    // sending the transaction
+    const txHash = await entrypoint.sendTransaction(transaction);
+
+    // wait for transaction completion, extract proposal's details
+    const outcome = await controller.awaitCompletedVote(txHash);
+    const proposalNonce = outcome[0].proposalNonce;
+    const vote = outcome[0].vote;
+    const voteTotalStake = outcome[0].totalStake;
+    const voteVotingPower = outcome[0].votingPower;
+}
+```
+
+#### Vote for a proposal using the factory
+```js
+{
+    // create the entrypoint and the governance factory
+    const entrypoint = new DevnetEntrypoint();
+    const factory = entrypoint.createGovernanceTransactionsFactory();
+
+    const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+    const alice = await Account.newFromPem(filePath);
+
+    const transaction = factory.createTransactionForVoting(alice.address, {
+        proposalNonce: 1,
+        vote: Vote.YES,
+    });
+    // fetch the nonce of the network
+    alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+    // set the nonce
+    transaction.nonce = alice.getNonceThenIncrement();
+
+    // sign the transaction
+    transaction.signature = await alice.signTransaction(transaction);
+
+    // sending the transaction
+    const txHash = await entrypoint.sendTransaction(transaction);
+
+    // wait for transaction completion, extract proposal's details
+    const transactionOnNetwork = await entrypoint.awaitCompletedTransaction(txHash);
+    const parser = new GovernanceTransactionsOutcomeParser({});
+    const outcome = parser.parseVote(transactionOnNetwork);
+    const proposalNonce = outcome[0].proposalNonce;
+    const vote = outcome[0].vote;
+    const voteTotalStake = outcome[0].totalStake;
+    const voteVotingPower = outcome[0].votingPower;
+}
+```
+
+#### Querying the governance contract
+Unlike creating transactions, querying the contract is only possible using the controller. Let's query the contract to get more details about a proposal.
+
+```js
+{
+    // create the entrypoint and the governance controller
+    const entrypoint = new DevnetEntrypoint();
+    const controller = entrypoint.createGovernanceController();
+
+    const proposalInfo = await controller.getProposal(1);
+    console.log({ proposalInfo });
+}
+```
+
 ## Addresses
 
 Create an `Address` object from a bech32-encoded string:

cookbook/delegation.ts

@@ -14,8 +14,8 @@ import { Account, Address, DevnetEntrypoint, TokenManagementTransactionsOutcomeP
     // - Undelegate and withdraw funds
 
     // These operations can be performed using both the controller and the **factory**. For a complete list of supported methods, please refer to the autogenerated documentation:
-    // - [DelegationController](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationController.html)
-    // - [DelegationTransactionsFactory](https://multiversx.github.io/mx-sdk-js-core/v14/classes/DelegationTransactionsFactory.html)
+    // - `class:DelegationController`
+    // - `class:DelegationTransactionsFactory`
 
     // #### Creating a New Delegation Contract Using the Controller
     // ```js

cookbook/generate.py

@@ -15,6 +15,7 @@
     current_dir / "delegation.ts",
     current_dir / "relayed.ts",
     current_dir / "guarded.ts",
+    current_dir / "governance.ts",
     current_dir / "addresses.ts",
     current_dir / "wallets.ts",
     current_dir / "signingObjects.ts",

cookbook/governance.ts

@@ -0,0 +1,172 @@
+import path from "path"; // md-ignore
+import { Account, DevnetEntrypoint, GovernanceTransactionsOutcomeParser, Vote } from "../src"; // md-ignore
+// md-start
+(async () => {
+    // ### Governance
+
+    // We can create transactions for creating a new governance proposal, vote for a proposal or query the governance contract.
+
+    // These operations can be performed using both the **controller** and the **factory**. For a complete list of supported methods, please refer to the autogenerated documentation:
+    // - `class:GovernanceController`
+    // - `class:GovernanceTransactionsFactory`
+
+    // #### Creating a new proposal using the controller
+    // ```js
+    {
+        // create the entrypoint and the governance controller // md-as-comment
+        const entrypoint = new DevnetEntrypoint();
+        const controller = entrypoint.createGovernanceController();
+
+        const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+        const alice = await Account.newFromPem(filePath);
+
+        // fetch the nonce of the network // md-as-comment
+        alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+        const commitHash = "1db734c0315f9ec422b88f679ccfe3e0197b9d67";
+
+        const transaction = await controller.createTransactionForNewProposal(alice, alice.getNonceThenIncrement(), {
+            commitHash: commitHash,
+            startVoteEpoch: 10,
+            endVoteEpoch: 15,
+            nativeTokenAmount: 500_000000000000000000n,
+        });
+
+        // sending the transaction // md-as-comment
+        const txHash = await entrypoint.sendTransaction(transaction);
+
+        // wait for transaction completion, extract proposal's details // md-as-comment
+        const outcome = await controller.awaitCompletedProposeProposal(txHash);
+
+        const proposalNonce = outcome[0].proposalNonce;
+        const proposalCommitHash = outcome[0].commitHash;
+        const proposalStartVoteEpoch = outcome[0].startVoteEpoch;
+        const proposalEndVoteEpoch = outcome[0].endVoteEpoch;
+    }
+    // ```
+
+    // #### Creating a new proposal using the factory
+    // ```js
+    {
+        // create the entrypoint and the governance factory // md-as-comment
+        const entrypoint = new DevnetEntrypoint();
+        const factory = entrypoint.createGovernanceTransactionsFactory();
+
+        const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+        const alice = await Account.newFromPem(filePath);
+
+        const commitHash = "1db734c0315f9ec422b88f679ccfe3e0197b9d67";
+
+        const transaction = factory.createTransactionForNewProposal(alice.address, {
+            commitHash: commitHash,
+            startVoteEpoch: 10,
+            endVoteEpoch: 15,
+            nativeTokenAmount: 500_000000000000000000n,
+        });
+        // fetch the nonce of the network // md-as-comment
+        alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+        // set the nonce // md-as-comment
+        transaction.nonce = alice.getNonceThenIncrement();
+
+        // sign the transaction // md-as-comment
+        transaction.signature = await alice.signTransaction(transaction);
+
+        // sending the transaction // md-as-comment
+        const txHash = await entrypoint.sendTransaction(transaction);
+
+        // waits until the transaction is processed and fetches it from the network // md-as-comment
+        const transactionOnNetwork = await entrypoint.awaitCompletedTransaction(txHash);
+
+        const parser = new GovernanceTransactionsOutcomeParser({});
+        const outcome = parser.parseNewProposal(transactionOnNetwork);
+        const proposalNonce = outcome[0].proposalNonce;
+        const proposalCommitHash = outcome[0].commitHash;
+        const proposalStartVoteEpoch = outcome[0].startVoteEpoch;
+        const proposalEndVoteEpoch = outcome[0].endVoteEpoch;
+    }
+    // ```
+
+    // #### Vote for a proposal using the controller
+
+    // ```js
+    {
+        // create the entrypoint and the governance controller // md-as-comment
+        const entrypoint = new DevnetEntrypoint();
+        const controller = entrypoint.createGovernanceController();
+
+        const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+        const alice = await Account.newFromPem(filePath);
+
+        // fetch the nonce of the network // md-as-comment
+        alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+        const transaction = await controller.createTransactionForVoting(alice, alice.getNonceThenIncrement(), {
+            proposalNonce: 1,
+            vote: Vote.YES,
+        });
+
+        // sending the transaction // md-as-comment
+        const txHash = await entrypoint.sendTransaction(transaction);
+
+        // wait for transaction completion, extract proposal's details // md-as-comment
+        const outcome = await controller.awaitCompletedVote(txHash);
+        const proposalNonce = outcome[0].proposalNonce;
+        const vote = outcome[0].vote;
+        const voteTotalStake = outcome[0].totalStake;
+        const voteVotingPower = outcome[0].votingPower;
+    }
+    // ```
+
+    // #### Vote for a proposal using the factory
+    // ```js
+    {
+        // create the entrypoint and the governance factory // md-as-comment
+        const entrypoint = new DevnetEntrypoint();
+        const factory = entrypoint.createGovernanceTransactionsFactory();
+
+        const filePath = path.join("../src", "testdata", "testwallets", "alice.pem");
+        const alice = await Account.newFromPem(filePath);
+
+        const transaction = factory.createTransactionForVoting(alice.address, {
+            proposalNonce: 1,
+            vote: Vote.YES,
+        });
+        // fetch the nonce of the network // md-as-comment
+        alice.nonce = await entrypoint.recallAccountNonce(alice.address);
+
+        // set the nonce // md-as-comment
+        transaction.nonce = alice.getNonceThenIncrement();
+
+        // sign the transaction // md-as-comment
+        transaction.signature = await alice.signTransaction(transaction);
+
+        // sending the transaction // md-as-comment
+        const txHash = await entrypoint.sendTransaction(transaction);
+
+        // wait for transaction completion, extract proposal's details // md-as-comment
+        const transactionOnNetwork = await entrypoint.awaitCompletedTransaction(txHash);
+        const parser = new GovernanceTransactionsOutcomeParser({});
+        const outcome = parser.parseVote(transactionOnNetwork);
+        const proposalNonce = outcome[0].proposalNonce;
+        const vote = outcome[0].vote;
+        const voteTotalStake = outcome[0].totalStake;
+        const voteVotingPower = outcome[0].votingPower;
+    }
+    // ```
+
+    // #### Querying the governance contract
+    // Unlike creating transactions, querying the contract is only possible using the controller. Let's query the contract to get more details about a proposal.
+
+    // ```js
+    {
+        // create the entrypoint and the governance controller // md-as-comment
+        const entrypoint = new DevnetEntrypoint();
+        const controller = entrypoint.createGovernanceController();
+
+        const proposalInfo = await controller.getProposal(1);
+        console.log({ proposalInfo });
+    }
+    // ```
+})().catch((e) => {
+    console.log({ e });
+});