github.com/hyperledger/burrow@v0.34.5-0.20220512172541-77f09336001d/docs/tutorials/8-proposals.md (about)

     1  # Proposals and Voting
     2  
     3  Proposals are a way of only executing some transactions if it receives enough votes. This can be 
     4  useful if, for example, there are some solidity contracts which are shared between multiple parties. The proposal
     5  (the transactions) are stored on-chain and other members can verify the proposal before voting on it. Once the
     6  proposal receives enough votes, it is instantly and atomically executed.
     7  
     8  ## Setup
     9  
    10  We want a chain with three participants and a root account for executing proposals. So, creates this with:
    11  
    12  ```shell
    13  burrow spec -v1 -r1 -p3  | burrow configure -s- -w genesis.json > burrow.toml
    14  ```
    15  
    16  Note that in the genesis doc there is a ProposalThreshold which is set to 3. This can be modified to suit your
    17  needs. We will leave it at three for now. However if you set this to 1, proposals will execute instantly since
    18  a proposal already has one vote once it is created (the proposer itself).
    19  
    20  ## Create a Proposal
    21  
    22  A proposal is a deployment yaml file, with some minor differences. The transactions which are to be proposed 
    23  should be contained in a proposal job, which should have a name and a description. This proposal jobs type has a 
    24  member called jobs. Store the jobs to be proposed here; each entry should have a source address which should
    25  ideally be a dedicated account for proposal. 
    26  
    27  No jobs of type `Assert` or `QueryContract` are allowed in a proposal.
    28  
    29  This is our Solidity contract we are proposing:
    30  
    31  ```solidity
    32  pragma solidity > 0.0.0;
    33  
    34  contract random {
    35  	function getInt() public pure returns (int) {
    36  		return 102;
    37  	}
    38  }
    39  ```
    40  
    41  A standard deploy yaml for this contract would be:
    42  
    43  ```yaml
    44  jobs:
    45   - name: deploy_random
    46     deploy:
    47       contract: random.sol
    48  ```
    49  
    50  And it would be deployed like so:
    51  
    52  ```shell
    53  burrow deploy -a Participant_0 random.yaml 
    54  ```
    55  
    56  Now we would like this to be a proposal. So, it needs to go into a proposal job and have it's source address
    57  set. The deploy yaml will look like:
    58  
    59  ```yaml
    60  jobs:
    61   - name: Propose Deploying contract random
    62     proposal:
    63       name: random.sol
    64       description: I says we should deploy random.sol
    65       jobs:
    66        - name: deploy_random
    67          deploy:
    68            source: Root_0
    69            contract: random.sol
    70  ```
    71  
    72  Now, to create this proposal:
    73  
    74  ```shell
    75  burrow deploy --proposal-create -a Participant_0 propose-random.yaml 
    76  ```
    77  
    78  The output should end with:
    79  
    80  ```shell
    81  log_channel=Info message="Creating Proposal" hash=5029B2B06D42A6339FBD9A97A230F914E3F655143C66B647979ACD05A04C8451
    82  ```
    83  
    84  # Vote for a Proposal
    85  
    86  So Participant_0 created a proposal. Now you are Participant_1, and Participant_0 tells you he's got this proposal
    87  he would like you to vote for. So first of all you want to list the current proposals:
    88  
    89  ```shell
    90  burrow deploy --list-proposals=PROPOSED
    91  ```
    92  
    93  ```shell
    94  log_channel=Info message=Proposal ProposalHash=5029b2b06d42a6339fbd9a97a230f914e3f655143c66b647979acd05a04c8451 Name=random.sol Description="I says we should deploy random.sol" State=PROPOSED Votes=1
    95  ```
    96  
    97  Now all we have is a hash. We want to know if this is really the change we are looking for. So, we can verify the proposal using the original deployment yaml and solidity files. You will need the same
    98  solidity compiler version for this to work.
    99  
   100  ```shell
   101  burrow deploy -a Participant_1 --proposal-verify propose-random.yaml 
   102  ```
   103  
   104  ```shell
   105  log_channel=Info message="Proposal VERIFY SUCCESSFUL" votescount=1
   106  log_channel=Info message=Vote no=0 address=0F73E4EF45EC20BDC7CF5A12EC2F32701C642B9C
   107  ```
   108  
   109  So the proposal is current, and matches the solidity and deployment files we have. We can now review those changes, and once we're happy with it, we can vote on it using:
   110  
   111  ```shell
   112  burrow deploy -a Participant_1 --proposal-vote propose-random.yaml 
   113  ```
   114  
   115  # Ratification and Execution
   116  
   117  Once Participant_2 has run:
   118  
   119  ```shell
   120  burrow deploy -a Participant_2 --proposal-vote propose-random.yaml 
   121  ```
   122  
   123  The contained transactions are executed. This happens in the same block as where the this vote is registered. 
   124  
   125  # Executed and Expired Proposals
   126  
   127  ```shell
   128  burrow deploy --list-proposals=ALL
   129  ```
   130  
   131  ```shell
   132  log_channel=Info message=Proposal ProposalHash=5029b2b06d42a6339fbd9a97a230f914e3f655143c66b647979acd05a04c8451 Name=random.sol Description="I says we should deploy random.sol" State=EXECUTED Votes=3
   133  ```
   134  
   135  Executing the transactions increased the sequence number of the Root_0 account. The transactions stored in the proposal
   136  depend on the sequence number being current. If Root_0 executed another transaction before the proposal executed, then
   137  the proposal would have become State=EXPIRED and it cannot not be voted any more.