From 32567e378b0e16ed0d65e97f3df98c83b8a1e132 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 07:15:30 -0600 Subject: [PATCH 1/9] new comments --- src/proposal.ts | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index bc6c2355..cd4d6d8b 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -511,25 +511,44 @@ export class Proposal implements IStateful { const threshold = realMathToNumber(new BN(item.gpQueue.threshold)) const stakesFor = new BN(item.stakesFor) const stakesAgainst = new BN(item.stakesAgainst) + /** + * for doing multiplication between floating point (threshold) and BN numbers + */ + const PRECISION = Math.pow(2, 40) - // upstakeNeededToPreBoost is the amount of tokens needed to upstake to move to the preboost queue - // this is only non-zero for Queued proposals - // note that the number can be negative! + /** + * The number of up-staking tokens (usually GEN) needed to qualify a queued proposal to move into the + * pre-boosted queue. + * + * Only computed for queued proposals. + * + * The equation is derived from: threshold = (stakesFor + upstakeNeededToPreBoost) / stakesAgainst + * + * >= 0 : any up-staked number of tokens greater than this will qualify to move the proposal to the preboost queue + * < 0 : the proposal ought already to be pre-boosted + */ let upstakeNeededToPreBoost: BN = new BN(0) - const PRECISION = Math.pow(2, 40) if (stage === IProposalStage.Queued) { - upstakeNeededToPreBoost = new BN(threshold * PRECISION) .mul(stakesAgainst) .div(new BN(PRECISION)) .sub(stakesFor) } - // upstakeNeededToPreBoost is the amount of tokens needed to upstake to move to the Queued queue - // this is only non-zero for Preboosted proposals - // note that the number can be negative! + + /** + * The number of down-staking tokens (usually GEN) needed to qualify a pre-boosted proposal to move back + * to the Queued queue. + * Only computed for PreBoosted proposals. + * + * The equation is derived from: threshold = stakesFor / (stakesAgainst + downStakeNeededToQueue) + * + * > 0 : any down-staked number of tokens equal to this will qualify to move the proposal to the Queued queue + * <= 0 : the proposal ought already to be in the Queued queue + */ let downStakeNeededToQueue: BN = new BN(0) if (stage === IProposalStage.PreBoosted) { - downStakeNeededToQueue = stakesFor.mul(new BN(PRECISION)) + downStakeNeededToQueue = stakesFor + .mul(new BN(PRECISION)) .div(new BN(threshold * PRECISION)) .sub(stakesAgainst) } From 24fa4e9aca4ea1c652440f93594ab04e44fa8550 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 07:20:36 -0600 Subject: [PATCH 2/9] tweak --- src/proposal.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/proposal.ts b/src/proposal.ts index cd4d6d8b..ebba9117 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -542,7 +542,8 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = stakesFor / (stakesAgainst + downStakeNeededToQueue) * - * > 0 : any down-staked number of tokens equal to this will qualify to move the proposal to the Queued queue + * > 0 : any down-staked number of tokens greater-than-or-equal to this will qualify to move the proposal + * to the Queued queue * <= 0 : the proposal ought already to be in the Queued queue */ let downStakeNeededToQueue: BN = new BN(0) From 99169c69a11be0b8a042e3f73ff8c1b10c458dd5 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 07:22:25 -0600 Subject: [PATCH 3/9] tweak --- src/proposal.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index ebba9117..70f5b6fa 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -524,8 +524,9 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = (stakesFor + upstakeNeededToPreBoost) / stakesAgainst * - * >= 0 : any up-staked number of tokens greater than this will qualify to move the proposal to the preboost queue - * < 0 : the proposal ought already to be pre-boosted + * > 0 : any up-staked number of tokens greater-than-or-equal to this will qualify to move the proposal + * to the preboost queue + * <= 0 : the proposal ought already to be pre-boosted */ let upstakeNeededToPreBoost: BN = new BN(0) if (stage === IProposalStage.Queued) { From d3fb95c9a18672eef739396d8b802114b5480986 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 07:26:41 -0600 Subject: [PATCH 4/9] fix --- src/proposal.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/proposal.ts b/src/proposal.ts index 70f5b6fa..0f89a3f1 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -526,7 +526,8 @@ export class Proposal implements IStateful { * * > 0 : any up-staked number of tokens greater-than-or-equal to this will qualify to move the proposal * to the preboost queue - * <= 0 : the proposal ought already to be pre-boosted + * == 0 : the proposal would remain in the Queued queue + * < 0 : the proposal ought already to be pre-boosted */ let upstakeNeededToPreBoost: BN = new BN(0) if (stage === IProposalStage.Queued) { From ba23cc6ef17f6c748b0c56f3c729de0d1774dca4 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 07:40:03 -0600 Subject: [PATCH 5/9] tweaks --- src/proposal.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index 0f89a3f1..0a0f393f 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -524,9 +524,8 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = (stakesFor + upstakeNeededToPreBoost) / stakesAgainst * - * > 0 : any up-staked number of tokens greater-than-or-equal to this will qualify to move the proposal + * >= 0 : any up-staked number of tokens greater than this will qualify to move the proposal * to the preboost queue - * == 0 : the proposal would remain in the Queued queue * < 0 : the proposal ought already to be pre-boosted */ let upstakeNeededToPreBoost: BN = new BN(0) @@ -546,7 +545,7 @@ export class Proposal implements IStateful { * * > 0 : any down-staked number of tokens greater-than-or-equal to this will qualify to move the proposal * to the Queued queue - * <= 0 : the proposal ought already to be in the Queued queue + * <= 0 : the proposal ought to alredy be in the Queued queue */ let downStakeNeededToQueue: BN = new BN(0) if (stage === IProposalStage.PreBoosted) { From e2ef3f625bbc3266191926cd7b2ed5c52b7e9ecd Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 09:17:09 -0600 Subject: [PATCH 6/9] slight rewording --- src/proposal.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index 0a0f393f..8c8e210b 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -524,7 +524,7 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = (stakesFor + upstakeNeededToPreBoost) / stakesAgainst * - * >= 0 : any up-staked number of tokens greater than this will qualify to move the proposal + * >= 0 : any number of up-staking tokens greater than this will qualify to move the proposal * to the preboost queue * < 0 : the proposal ought already to be pre-boosted */ @@ -543,7 +543,7 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = stakesFor / (stakesAgainst + downStakeNeededToQueue) * - * > 0 : any down-staked number of tokens greater-than-or-equal to this will qualify to move the proposal + * > 0 : any number of down-staking tokens greater-than-or-equal to this will qualify to move the proposal * to the Queued queue * <= 0 : the proposal ought to alredy be in the Queued queue */ From a29c22e0d341ffacea0e64629a5b560910cdafae Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Fri, 6 Mar 2020 11:42:31 -0600 Subject: [PATCH 7/9] spelling --- src/proposal.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/proposal.ts b/src/proposal.ts index 8c8e210b..7d7e52dd 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -545,7 +545,7 @@ export class Proposal implements IStateful { * * > 0 : any number of down-staking tokens greater-than-or-equal to this will qualify to move the proposal * to the Queued queue - * <= 0 : the proposal ought to alredy be in the Queued queue + * <= 0 : the proposal ought to already be in the Queued queue */ let downStakeNeededToQueue: BN = new BN(0) if (stage === IProposalStage.PreBoosted) { From 19c7ea90a1a757e0bf7862f4773027d018ca9415 Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Mon, 9 Mar 2020 17:57:37 -0600 Subject: [PATCH 8/9] requested tweak to the comments --- src/proposal.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index 7d7e52dd..1426b721 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -524,9 +524,11 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = (stakesFor + upstakeNeededToPreBoost) / stakesAgainst * - * >= 0 : any number of up-staking tokens greater than this will qualify to move the proposal + * Where `upstakeNeededToPreBoost` is: + * + * >= 0 : then any number of up-staking tokens greater than it will qualify to move the proposal * to the preboost queue - * < 0 : the proposal ought already to be pre-boosted + * < 0 : then the proposal ought already to be pre-boosted */ let upstakeNeededToPreBoost: BN = new BN(0) if (stage === IProposalStage.Queued) { @@ -543,9 +545,11 @@ export class Proposal implements IStateful { * * The equation is derived from: threshold = stakesFor / (stakesAgainst + downStakeNeededToQueue) * - * > 0 : any number of down-staking tokens greater-than-or-equal to this will qualify to move the proposal + * When `downStakeNeededToQueue` is: + * + * > 0 : then any number of down-staking tokens greater-than-or-equal to it will qualify to move the proposal * to the Queued queue - * <= 0 : the proposal ought to already be in the Queued queue + * <= 0 : then the proposal ought to already be in the Queued queue */ let downStakeNeededToQueue: BN = new BN(0) if (stage === IProposalStage.PreBoosted) { From b22eb7044545639d5715637e00ee7d774ecd8b7d Mon Sep 17 00:00:00 2001 From: Doug Kent Date: Mon, 9 Mar 2020 18:01:21 -0600 Subject: [PATCH 9/9] lint --- src/proposal.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/proposal.ts b/src/proposal.ts index 1426b721..15be06d8 100644 --- a/src/proposal.ts +++ b/src/proposal.ts @@ -526,8 +526,8 @@ export class Proposal implements IStateful { * * Where `upstakeNeededToPreBoost` is: * - * >= 0 : then any number of up-staking tokens greater than it will qualify to move the proposal - * to the preboost queue + * >= 0 : then any number of up-staking tokens greater than upstakeNeededToPreBoost will qualify + * to move the proposal to the preboost queue * < 0 : then the proposal ought already to be pre-boosted */ let upstakeNeededToPreBoost: BN = new BN(0) @@ -547,8 +547,8 @@ export class Proposal implements IStateful { * * When `downStakeNeededToQueue` is: * - * > 0 : then any number of down-staking tokens greater-than-or-equal to it will qualify to move the proposal - * to the Queued queue + * > 0 : then any number of down-staking tokens greater-than-or-equal to downStakeNeededToQueue will qualify + * to move the proposal to the Queued queue * <= 0 : then the proposal ought to already be in the Queued queue */ let downStakeNeededToQueue: BN = new BN(0)