04_vote.md
1 # Vote Example Tutorial 2 In some scenarios, developers may wish to use more sophisticated governance mechanisms to manage program updates. 3 In these cases, developers can use the `"checksum"` configuration. 4 At a high-level, every AVM program has a unique checksum associated with it. We can use this checksum to pin down the expected contents of a program. 5 6 This tutorial details a "toy" voting system for program updates on the Aleo network. 7 In production, extra care should be taken to ensure that the governance mechanism is secure and robust. 8 9 ## Initializing the Project 10 You may either use the existing `vote` project 11 ``` 12 > cd vote 13 ``` 14 or create a new Leo project with the following command: 15 ``` 16 > leo new vote 17 ``` 18 19 20 21 ## Program Overview 22 23 This project will contain two programs: `basic_voting.alpha` and `vote_example.alpha`. 24 25 The `basic_voting` program is a non-upgradable program (see `01_noupgrade.md` for more details) that allows users to propose the expected checksum and vote on it them. 26 Note that the voting program is intended for educational purposes and is **NOT** suitable for production use. 27 See `vote_example/basic_voting` for the source code. 28 29 The main program (`vote_example.alpha`) imports the `basic_voting` program and queries the `approved_checksum` mapping to determine the expected checksum for the program. 30 ```leo 31 import basic_voting.alpha; 32 33 program vote_example.alpha { 34 @checksum(mapping="basic_voting.alpha/approved_checksum", key="true") 35 async constructor() {} 36 37 transition main(public a: u32, b: u32) -> u32 { 38 let c: u32 = a + b; 39 return c; 40 } 41 42 // Uncomment me to test the upgrade. 43 // transition foo() {} 44 } 45 ``` 46 47 The `"mapping"` field specifies the program and mapping to look at for the approved checksum. 48 The `"key"` field specifies the hard-coded key that will be accessed to retrieve the expected checksum. 49 The Leo compiler will generate AVM code that checks that the program's checksum matches the approved checksum in the `basic_voting` program. 50 51 ## Step-by-Step Guide 52 53 ### Deploying the Program 54 55 First, deploy both programs to the Aleo network: 56 57 ``` 58 leo deploy --broadcast 59 . 60 . 61 . 62 🔧 Your program 'vote_example.alpha' has the following constructor. 63 ────────────────────────────────────────────── 64 constructor: 65 branch.eq edition 0u16 to end; 66 get basic_voting.alpha/approved_checksum[true] into r0; 67 assert.eq checksum r0; 68 position end; 69 ────────────────────────────────────────────── 70 Once it is deployed, it CANNOT be changed. 71 . 72 . 73 . 74 ``` 75 76 ### Developing the Upgrade 77 To test the upgrade functionality, we can try to deploy the same program again. 78 You may also try to modify the program to add a new function. 79 Please refer to the [documentation](https://docs.leo-lang.org/guides/upgradability) for more details on what constitutes a valid upgrade. 80 81 `leo build` will compile the program and tell us what the checksum is. This will be used to propose the upgrade. 82 83 ```bash 84 > leo build 85 Leo 86 43 statements before dead code elimination. 87 Leo 43 statements after dead code elimination. 88 Leo The program checksum is: '[236u8, 187u8, 121u8, 19u8, 43u8, 151u8, 43u8, 148u8, 186u8, 84u8, 247u8, 47u8, 61u8, 191u8, 25u8, 144u8, 160u8, 154u8, 95u8, 43u8, 177u8, 250u8, 189u8, 109u8, 243u8, 208u8, 52u8, 113u8, 202u8, 82u8, 216u8, 66u8]'. 89 Leo ✅ Compiled 'basic_voting.alpha' into Aleo instructions. 90 Leo 91 12 statements before dead code elimination. 92 Leo 12 statements after dead code elimination. 93 Leo The program checksum is: '[33u8, 48u8, 194u8, 27u8, 174u8, 61u8, 90u8, 33u8, 29u8, 160u8, 246u8, 222u8, 188u8, 64u8, 174u8, 4u8, 25u8, 255u8, 119u8, 147u8, 218u8, 75u8, 182u8, 78u8, 213u8, 89u8, 77u8, 100u8, 247u8, 125u8, 72u8, 3u8]'. 94 Leo ✅ Compiled 'vote_example.alpha' into Aleo instructions. 95 ``` 96 97 The checksum that we will propose is: `[33u8, 48u8, 194u8, 27u8, 174u8, 61u8, 90u8, 33u8, 29u8, 160u8, 246u8, 222u8, 188u8, 64u8, 174u8, 4u8, 25u8, 255u8, 119u8, 147u8, 218u8, 75u8, 182u8, 78u8, 213u8, 89u8, 77u8, 100u8, 247u8, 125u8, 72u8, 3u8]` 98 99 ### Invalid Upgrade Attempts 100 101 Now let's try to deploy the program without going through the voting process. 102 This will fail because there is no approved checksum set in the `basic_voting` program. 103 ```bash 104 leo upgrade --broadcast 105 ``` 106 107 ### Voting on the Upgrade 108 109 To propose the upgrade, we need to call the `propose` transition in the `basic_voting` program. 110 ```bash 111 leo execute basic_voting.alpha propose "[33u8, 48u8, 194u8, 27u8, 174u8, 61u8, 90u8, 33u8, 29u8, 160u8, 246u8, 222u8, 188u8, 64u8, 174u8, 4u8, 25u8, 255u8, 119u8, 147u8, 218u8, 75u8, 182u8, 78u8, 213u8, 89u8, 77u8, 100u8, 247u8, 125u8, 72u8, 3u8]" --broadcast 112 ``` 113 114 Then we'll need to vote on the proposal. 115 We'll vote once with our own address. 116 ```bash 117 leo execute basic_voting.alpha vote "[33u8, 48u8, 194u8, 27u8, 174u8, 61u8, 90u8, 33u8, 29u8, 160u8, 246u8, 222u8, 188u8, 64u8, 174u8, 4u8, 25u8, 255u8, 119u8, 147u8, 218u8, 75u8, 182u8, 78u8, 213u8, 89u8, 77u8, 100u8, 247u8, 125u8, 72u8, 3u8]" true --broadcast 118 ``` 119 And then once more with a different address. 120 ```bash 121 leo execute basic_voting.alpha vote "[33u8, 48u8, 194u8, 27u8, 174u8, 61u8, 90u8, 33u8, 29u8, 160u8, 246u8, 222u8, 188u8, 64u8, 174u8, 4u8, 25u8, 255u8, 119u8, 147u8, 218u8, 75u8, 182u8, 78u8, 213u8, 89u8, 77u8, 100u8, 247u8, 125u8, 72u8, 3u8]" true --broadcast --private-key 122 APrivateKey1zkp2RWGDcde3efb89rjhME1VYA8QMxcxep5DShNBR6n8Yjh 123 ``` 124 Note: The key `APrivateKey1zkp2RWGDcde3efb89rjhME1VYA8QMxcxep5DShNBR6n8Yjh` will always have credits on a local snarkOS development network. 125 126 ### Another Invalid Upgrade Attempt 127 Now let's try to deploy the program, but modify the code so that the checksum does not match the approved checksum. 128 For example, we can change the name of the `foo` transition to `foo2`. 129 If we attempt to upgrade the program now, it will fail because the checksum does not match the approved checksum. 130 ```bash 131 leo upgrade --skip basic_voting.alpha --broadcast 132 ``` 133 134 ## A Successful Upgrade 135 Finally, let's modify the program to match the approved checksum and deploy it. 136 We'll change the `foo2` transition back to its original name `foo` and then run the upgrade command again. 137 ```bash 138 leo upgrade --skip basic_voting.alpha --broadcast 139 ``` 140 141 We can verify by checking that the new program is present in the network. 142 ```bash 143 leo query program vote_example.alpha 144 ``` 145 146 147 148 149 150