# 6. auditor.bos - a contract that elect the auditors for boswps.io This contract will be in charge of auditor registration and voting for BOS auditors. When an auditor registers, they need to provide their bio by calling the `updatebio` action. If an elected auditor resigns via the `withdrawcand` during a period a new candidate will be chosen to fill the gap on the auditor board from the votes ranking in the candidates at that moment. #### Quickstart **ACTION eosio.token::transfer & nominatecand** > Nominate Candidate > > Must `eosio::transfer` BOS tokens at a minimum of `lockupasset` (100.0000 BOS). Once candidate has meet the minimum locked tokens threshold, they will be automatically set as an active candidate able to receive votes from BOS users. ``` $ bosc transfer auditor.bos "100.0000 BOS" -m "stake for auditor.bos" ``` OR ``` $ bosc tx create auditor.bos nominatecand '{"cand": ""}' -p @active ``` **ACTION vote** > Vote for Auditor Candidate ``` $ bosc tx create auditor.bos vote '{"voter":"","newvotes":["", "",""], "vote_json":""}' -p deniscarrier ``` **ACTION unvote** > Removes existing vote from `voter`. ``` $ bosc tx create auditor.bos unvote '{"voter": ""}' -p @active ``` **Withdraw Candidate & Unstake** > A Candidate must `withdrawcand` to be allowed to `unstake` any BOS assets that was sent to `auditor.bos`. ``` $ bosc tx create auditor.bos withdrawcand '{"cand":""}' -p $ bosc tx create auditor.bos unstake '{"cand":""}' -p ``` **ACTION resign** > Resign as Auditor > > Removes elected auditor from `auditor.bos@auditors` ``` $ bosc tx create auditor.bos resign '{"auditor":""}' -p ``` **ACTION newtenure** > Start Auditor Tenure (Election) > > `auditor.bos@auditors` permission will `updateauth` with candidates with the highest votes ``` $ bosc tx create auditor.bos newtenure '{"candidates": ["", ""], "message":"newtenure for auditor.bos"}' -p auditor.bos@active ``` **ACTION fireauditor** > Removes Auditor from `auditor.bos@auditors` authority ``` $ bosc tx create auditor.bos fireauditor '{"auditor": ""}' -p auditor.bos@active ``` **ACTION resign** > Removes Auditor from `auditor.bos@auditors` authority ``` $ bosc tx create auditor.bos resign '{"auditor": ""}' -p @active ``` **ACTION cleancand** > Used to clean `candidate` data entry Authorized by `require_auth( _self )` * set `total_votes` to 0 * set `is_active` if locked\_tockens met minimum threshold ``` $ bosc tx create auditor.bos cleancand '{"cand": ""}' -p auditor.bos@active ``` **ACTION cleanvoter** > Used to clean `voter` data entry Authorized by `require_auth( _self )` * If voter has not voted for any candidates, remove voter from `votes` & `votejson` * Update voter's staked & proxy data * Add `vote_json` if not present in `votejson` table ``` $ bosc tx create auditor.bos cleanvoter '{"voter": ""}' -p auditor.bos@active ``` #### Tables **candidates** * `candidate_name` (name) - Account name of the candidate * `locked_tokens` (asset) - An asset object representing the number of tokens locked when registering * `total_votes` (uint64) - Updated tally of the number of votes cast to a candidate. This is updated and used as part of the `newtenure` calculations. It is updated every time there is a vote change or a change of token balance for a voter for this candidate to facilitate live voting stats. * `is_active` (bool) - Boolean indicating if the candidate is currently available for election. * `unstaking_end_time_stamp` (time\_point\_sec) - timestamp that user is allowed to unstake tokens. **auditors** * `auditor_name` (name) - Account name of the auditor **votes** * `voter` (name) - The account name of the voter * `proxy` (name) - DEPRECATED: the proxy set by the voter, if any (not being used to count final vote tally) * `staked` (uint64) - DEPRECATED: total staked amount of voter (not being used to count final vote tally) * `candidates` (name\[]) - The candidates voted for, can supply up to the maximum number of votes (currently 5) - Can be configured via `updateconfig` **votejson** * `voter` (name) - The account name of the voter * `vote_json` (string JSON)- JSON metadata for voting (ex: {"comment": "great work"}) * `updated_at` (time\_point\_sec) last updated timestamp #### bios * `candidate_name` (name) - Account name of candidate * `bio` (string JSON) - Bio of candidate **config** * `lockupasset` (asset) - The amount of assets that are locked up by each candidate applying for election. * `maxvotes` (int default=3) - The maximum number of votes that each member can make for a candidate. * `numelected` (int default=5) - Number of auditors to be elected for each election count. * `authaccount` ( account= "auditor.bos") - account to have active auth set with all auditors on the newtenure. * `auth_threshold_auditors` (uint8) - Number of auditors required to approve the lowest level actions. * `lockup_release_time_delay` (date) - The time before locked up stake can be released back to the candidate using the unstake action #### Actions ### updatebio #### Description To allow a candidate update their bio information after they have nominated. The action ensures the user has agreed to the latest terms and conditions, has the correct authorization of the to perform the action and is already nominated as a candidate. Then the bio information for the candidate will be updated leaving all other data of the candidate unchanged. ### fireauditor #### Description To allow elected auditors to (where quorum and configured majorities are met) to remove a fellow auditor and lock up their tokens until the configured delay period has passed. ### resign #### Description To remove an elected auditor. This action must be run by the resigning auditor and the outcome should remove the elected auditor and lock up their tokens until the delay period has passed so the tokens can be claimed with the unstake action. ### firecand #### Description The intent of forehand is to set a candidate to a state of inactive so they will be excluded from the next election round. This action may only be run by the by elected auditors (where quorum and configured majorities are met). There is an option to lock up the candidate's tokens until a delay period has passed based on the delay set in the config after which the tokens can be claimed with the unstake action. If the option passed is false and there is an existing lockup delay on the tokens then this lockup will continue to be active until the lock up time has passed. ### unstake #### Description To return staked tokens back to the candidate if the user is no longer an active candidate and there is no delay set on the candidate the staked tokens will be returned to the candidate. **TERM:** This action lasts for the duration of the time taken to process the transaction. ### updateconfig Update the configuration for the running contract of selected parameters without needing change the source code. This requires a privileged account. ### nominatecand **V1.0 Auditor’s Declaration of Independence and Impartiality** I, , accept to serve as Auditor, in accordance with the BOS Rules. I **DECLARE** to be and to intend to remain independent and impartial during the auditing procedure. **DECLARE** that, to my knowledge, there are no facts, circumstances or relationships which may affect my independence and impartiality. **DECLARE** to treat all BOS members fairly, reward contributions appropriately and not seek unmerited profits. No member should have less or more information about an auditing decision than others. **DECLARE** not to seek any stake in, or exert undue influence over, other block producers and shall take appropriate measures to protect my own independence and impartiality. #### Description The intent of is to nominates a candidate to auditor election, Accounts must nominate as a candidate before they can be voted for. The candidate must lock a configurable number of tokens before trying to nominate (configurable via in the parameter lockupasset which will be sent from the token contract as defined and set in the code of the contract. If a user previously been a candidate they may have enough staked tokens to not require further staking but will otherwise need to transfer the difference to meet the required stake. ### withdrawcand #### Description To withdraw a candidate for becoming an elected auditor. The action ensures the account is currently nominated. On success the amount of tokens that was locked up via the action will be added to a list of pending transactions to transfer back to the account. The actual transfer would be performed by a separate action due to the auth requirement for sending funds from the contract's account. ### vote #### Description To allow a member of BOS to vote for candidates that are eligible become auditors after the next call to . The action ensures the user has agreed to the latest terms and conditions and has the correct authorization of the account: to place or change an active vote. Upon success this action will either update an existing vote with a new set of candidates or create a new active vote for the for candidates eligible for election. ### newtenure #### Description To signal the end of one election period and commence the next. It performs several actions after the following conditions are met: * The action is not called before the period should have ended * Enough voter value has participated to trigger the initial running of the BOS * After BOS auditors has started enough voter value has continued engagement with the BOS auditor voting process. * Set the permissions for the elected auditors so they have sufficient permission to run the BOS auditor permission according to the constitution and technical permissions design. * Set the time for the beginning of the next period to mark the reset anniversary for the BOS auditor elections. ### claimpay #### Description The intent of is to allow an account to claim pending payment amounts due to the account. The pay claim they are claiming needs to be visible in the `pendingpay` table. Transfers to the claimer via an inline transfer on the `eosio.token` contract and then removes the pending payment record from the `pending_pay` table. The active auth of this claimer is required to complete this action. ### unvote #### Description Removes existing vote from . #### Description MAINTENANCE action used to refresh