[contract] updating README and CLI descriptions

packages/validator-bonds-cli/README.md

@@ -38,9 +38,43 @@ validator-bonds --help
 
 * [creating a bond](#creating-a-bond)
 * [funding the bond](#funding-bond-account)
-# TODO: bidding requires more detailed description
 * [bidding for the stake](#bond-account-configuration)
-* [during the time of tracking, the bond is sufficiently funded](#show-the-bond-account)
+* [track that the bond is sufficiently funded](#show-the-bond-account)
+
+
+In terms of CLI commands in the most simplistic way:
+
+```sh
+# initializing the bond account for vote-account
+validator-bonds init-bond --vote-account <vote-account-address> \
+  --validator-identity ./validator-identity.json
+> Bond account BondAddress9iRYo3ZEK6dpmm9jYWX3Kb63Ed7RAFfUc of config vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 successfully created
+
+# optional: grind stake account keypair, used to remind that the key is for a bond
+solana-keygen grind --starts-with bnd:1
+> Wrote keypair to bndozK6C9zuCqjrdaWoJpX9AQeU1jm8BNdmKC85LotQ.json
+
+# Creating a stake account. The SOLs will be funded to the Bond
+solana create-stake-account <stake-account-keypair> <Amount of SOL 1 for every 10,000 staked>
+
+# To couple the created stake account with the vote account
+solana delegate-stake <stake-account-pubkey> <vote-account-address>
+
+<Wait for the stake to activate in the next epoch>
+
+# Funding Bond by assigning the stake account with the SOL amount in it
+validator-bonds fund-bond <vote-account-address> --stake-account <stake-account-pubkey>
+
+# Bidding the auction
+# --max-stake-wanted defines the maximum stake amount (in SOLs) the validator wants to be delegated to them
+# --cpmpe defines how many lamports the validator is willing to pay for every 1000 SOLs delegated
+validator-bonds configure-bond <vote-account-address> --authority ./validator-identity.json \
+  --cpmpe <lamports> --max-stake-wanted <SOLs>
+> Bond account BondAddress9iRYo3ZEK6dpmm9jYWX3Kb63Ed7RAFfUc successfully configured
+
+# Check the new configuration and track the funding
+validator-bonds show-bond <vote-account-address>
+```
 
 
 ### Creating a bond
@@ -90,18 +124,17 @@ The parameters and their meanings are explained in detail below:
 * `--bond-authority`: Refers to any public key with ownership rights. It is recommended to use a ledger or multisig. This key does not necessarily need to correspond to an existing on-chain account (SOL preloading is unnecessary).
 * `--rent-payer`: This account covers the creation cost of the Solana bond account, and it is expected to be the same as the fee payer (default).
    The rent cost is `0.00270048` SOL. Note that the `--rent-payer` is unrelated to bond security or "funding," which is addressed through a separate instruction. The bond's security is established by providing a stake account. The lamports in the stake account then corresponds to the SOL amount added to the security of the bond account. There is no direct payment of SOLs to the bond; it is accomplished solely by allocating stake accounts.
-* `--cpmpe`: cost per mille per epoch. In lamports. It configures the bid that the `Bond` owner
-  wish to pay for receiving delegated stake. The maximum provided delegated stake is defined
-  by `max-stake-wanted`. The actual amount of delegated stake is influenced by constraints defined by
-  [delegation strategy](https://docs.marinade.finance/marinade-protocol/validators).
-  The value of of `cpmpe` goes into the auction and based on the other
-  bids the delegation strategy then delegates the actual amount of stake to the vote account
-  coupled with the `Bond` account.
-  The funded bond is charged only for amount of stake that was really delegated.
-  When nothing is delegated to the vote account, then nothing is charged from the `Bond` account.
-* `--max-stake-wanted`: In lamports. The maximum number of stake the `Bond` owner desires
-  to get delegated from
+* `--cpmpe`: Cost per mille per epoch, in lamports. How many lamports the validator is willing to pay
+  for every 1000 SOLs delegated.
+  The property configures the bid the `Bond` owner wishes to pay for receiving delegated stake. The maximum delegated stake is defined by `max-stake-wanted`.
+  The actual amount of delegated stake is influenced by constraints defined by the
   [delegation strategy](https://docs.marinade.finance/marinade-protocol/validators).
+  The `cpmpe` value goes into the auction where compared with other bids the delegation strategy determines
+  the actual amount of stake delegated to the vote account linked to the `Bond` account.
+* `--max-stake-wanted`: The maximum stake, in SOLs, that the `Bond` owner desires to get delegated
+  from the [delegation strategy](https://docs.marinade.finance/marinade-protocol/validators).
+  The funded bond is charged only for the amount of stake that was actually delegated
+  (if nothing is delegated, nothing is charged).
 
 ### Show the bond account
 
@@ -119,13 +152,13 @@ Expected output on created bond is like
     config: 'vbMaRfmTCg92HWGzmd53APkMNpPnGVGZTUHwUJQkXAU',
     voteAccount: '...',
     authority: '...'
-    costPerMillePerEpoch: 0,
-    maxStakeWanted: 0
+    costPerMillePerEpoch: "1000 lamports",
+    maxStakeWanted: "10000 SOLs"
 
   },
-  amountActive: 10024261277,
-  amountAtSettlements: 0,
-  amountToWithdraw: 0,
+  amountActive: "10.024261277 SOLs,
+  amountAtSettlements: "0.000000000 SOL",
+  amountToWithdraw: "0.000000000 SOL",
   numberActiveStakeAccounts: 1,
   numberSettlementStakeAccounts: 0,
   withdrawRequest: '<NOT EXISTING>'
@@ -136,16 +169,15 @@ Expected output on created bond is like
 
 The `Bond` owner may configure following properties of the account:
 
-* `--bond-authority`: authority that when it signs the configuration transaction
-  then it permits to change the `Bond` account configuration and to withdraw funds.
-  The same ability to configure the `Bond` has got the signature 
-  of validator identity keypair of the coupled `vote account`,
-  or owner of the [SPL minted configuration token](#permission-less-mint---configure-workflow).
-* `--cpmpe`: cost per mille per epoch (in lamports). It's a bid used in delegation strategy auction.
-  The `Bond` owner defines his attitude to pay that amount in lamports to get stake delegated
-  to vote account for one epoch.
-* `--max-stake-wanted`: the maximum amount stake that the `Bond` owner desired
-  to get delegated to his vote account.
+* `--bond-authority`: The authority that, when signing the configuration transaction,
+  allows changes to the `Bond` account configuration and withdrawal of funds.
+  The validator identity keypair of the linked `vote account` or the owner of the
+  [SPL minted configuration token](#permission-less-mint---configure-workflow) also has this ability.
+* `--cpmpe`: Cost per mille per epoch (in lamports). It's a bid used in the delegation strategy
+  auction. The Bond owner agrees to pay this amount in lamports to get stake delegated to the vote
+  account for one epoch.
+* `--max-stake-wanted` In SOLs, the maximum amount of stake that the Bond owner desires to get delegated
+  to their vote account. 
 
 #### Permission-ed Configure workflow
 
@@ -197,19 +229,6 @@ validator-bonds -um configure-bond <bond-or-vote-account-address> \
   --with-token
 ```
 
-#### Bond configuration
-
-The `Bond` owner may configure following properties of the account:
-
-* `--bond-authority`: authority that when it signs the configuration transaction
-  then it permits to change the `Bond` account configuration and to withdraw funds.
-  The same ability has got the `vote account` withdraw authority coupled with the `Bond`
-  or owner of the [SPL minted configuration token](#permission-less-mint---configure-workflow).
-* `--cpmpe`: cost per mille per epoch (in lamports). It's a bid used in delegation strategy auction.
-  The `Bond` owner defines his attitude to pay that amount in lamports to get stake delegated
-  to vote account for one epoch.
-* `--max-stake-wanted`: the maximum amount stake that the `Bond` owner desired
-  to get delegated to his vote account.
 
 ### Funding Bond Account
 
@@ -244,27 +263,6 @@ The meanings of parameters are as follows:
 - `--stake-authority`: signature of the stake account authority that permits to change the
   stake account authorities
 
-#### Bond Account initialization and funding SHOWCASE (credits to [Bored King](https://twitter.com/bape_SOL))
-
-```sh
-validator-bonds init-bond --vote-account <vote-account-address> \
-  --validator-identity ./identity.json --keypair ./identity.json
-> Bond account BondAddress9iRYo3ZEK6dpmm9jYWX3Kb63Ed7RAFfUc of config vBoNdEvzMrSai7is21XgVYik65mqtaKXuSdMBJ1xkW4 successfully created
-
-solana-keygen grind --starts-with bnd:1
-> Optional: Grind is used to remind the key is for bond a bond.
-> bndk55Q9YntUzpHvnAy9bcbtdHYfFjANUfjsCECF1ba.json
-
-solana create-stake-account ./bndk55Q9YntUzpHvnAy9bcbtdHYfFjANUfjsCECF1ba.json <Amount of SOL 1 for every 10,000 staked>
-
-solana delegate-stake ./bndk55Q9YntUzpHvnAy9bcbtdHYfFjANUfjsCECF1ba.json <Vote Pubkey>
-
-<wait for stake to activate in next epoch>
-
-validator-bonds fund-bond BondAddress9iRYo3ZEK6dpmm9jYWX3Kb63Ed7RAFfUc \
-  --stake-account bndk55Q9YntUzpHvnAy9bcbtdHYfFjANUfjsCECF1ba --keypair ./identity.json
-```
-
 #### How to add more funds under the bond?
 
 It's as simple as creating a new stake account and funding it into the bond program.

packages/validator-bonds-cli/__tests__/test-validator/configureBond.spec.ts

@@ -4,7 +4,7 @@ import {
   pubkey,
 } from '@marinade.finance/web3js-common'
 import { shellMatchers } from '@marinade.finance/jest-utils'
-import { Keypair, PublicKey } from '@solana/web3.js'
+import { Keypair, LAMPORTS_PER_SOL, PublicKey } from '@solana/web3.js'
 import {
   ValidatorBondsProgram,
   bondAddress,
@@ -159,7 +159,7 @@ describe('Configure bond account using CLI', () => {
     const bondsData2 = await getBond(program, bondAccount)
     expect(bondsData2.authority).toEqual(newBondAuthority)
     expect(bondsData2.cpmpe).toEqual(32)
-    expect(bondsData2.maxStakeWanted).toEqual(1000)
+    expect(bondsData2.maxStakeWanted).toEqual(1000 * LAMPORTS_PER_SOL)
   })
 
   it('configure bond account with mint', async () => {
@@ -261,7 +261,7 @@ describe('Configure bond account using CLI', () => {
     const bondsData = await getBond(program, bondAccount)
     expect(bondsData.authority).toEqual(newBondAuthority)
     expect(bondsData.cpmpe).toEqual(2)
-    expect(bondsData.maxStakeWanted).toEqual(999)
+    expect(bondsData.maxStakeWanted).toEqual(999 * LAMPORTS_PER_SOL)
   })
 
   it('configure bond in print-only mode', async () => {

packages/validator-bonds-cli/__tests__/test-validator/initBond.spec.ts

@@ -124,7 +124,7 @@ describe('Init bond account using CLI', () => {
     expect(bondsData.voteAccount).toEqual(voteAccount)
     expect(bondsData.authority).toEqual(bondAuthority.publicKey)
     expect(bondsData.cpmpe).toEqual(33)
-    expect(bondsData.maxStakeWanted).toEqual(1000)
+    expect(bondsData.maxStakeWanted).toEqual(1000 * LAMPORTS_PER_SOL)
     expect(bondsData.bump).toEqual(bump)
     await expect(
       provider.connection.getBalance(rentPayerKeypair.publicKey)

packages/validator-bonds-cli/__tests__/test-validator/show.spec.ts

@@ -254,7 +254,7 @@ describe('Show command using CLI', () => {
       voteAccount,
       validatorIdentity,
       cpmpe: 222,
-      maxStakeWanted: 2000,
+      maxStakeWanted: 2000 * LAMPORTS_PER_SOL,
     })
 
     const expectedDataNoFunding = {
@@ -264,15 +264,15 @@ describe('Show command using CLI', () => {
         config: configAccount.toBase58(),
         voteAccount: voteAccount.toBase58(),
         authority: bondAuthority.publicKey.toBase58(),
-        costPerMillePerEpoch: 222,
-        maxStakeWanted: 2000,
+        costPerMillePerEpoch: '222 lamports',
+        maxStakeWanted: '2000 SOLs',
       },
     }
     const expectedData = {
       ...expectedDataNoFunding,
-      amountActive: 0,
-      amountAtSettlements: 0,
-      amountToWithdraw: 0,
+      amountActive: '0.000000000 SOL',
+      amountAtSettlements: '0.000000000 SOL',
+      amountToWithdraw: '0.000000000 SOL',
       numberActiveStakeAccounts: 0,
       numberSettlementStakeAccounts: 0,
       withdrawRequest: '<NOT EXISTING>',
@@ -501,15 +501,15 @@ describe('Show command using CLI', () => {
         config: configAccount,
         voteAccount: voteAccount,
         authority: bondAuthority.publicKey,
-        costPerMillePerEpoch: 1,
-        maxStakeWanted: 0,
+        costPerMillePerEpoch: '1 lamport',
+        maxStakeWanted: '0 SOL',
       },
     }
     const expectedData = {
       ...expectedDataNoFunding,
-      amountActive: 0,
-      amountAtSettlements: 0,
-      amountToWithdraw: 0,
+      amountActive: '0.000000000 SOL',
+      amountAtSettlements: '0.000000000 SOL',
+      amountToWithdraw: '0.000000000 SOL',
       numberActiveStakeAccounts: stakeAccountLamports.length,
       numberSettlementStakeAccounts: 0,
       withdrawRequest: '<NOT EXISTING>',
@@ -538,7 +538,7 @@ describe('Show command using CLI', () => {
       // stderr: '',
       stdout: YAML.stringify({
         ...expectedData,
-        amountActive: sumLamports,
+        amountActive: `${sumLamports / LAMPORTS_PER_SOL}.000000000 SOLs`,
       }),
     })
 
@@ -581,16 +581,22 @@ describe('Show command using CLI', () => {
       // stderr: '',
       stdout: YAML.stringify({
         ...expectedData,
-        amountActive: sumLamports - withdrawRequestAmount,
-        amountToWithdraw: withdrawRequestAmount,
+        amountActive: `${
+          (sumLamports - withdrawRequestAmount) / LAMPORTS_PER_SOL
+        }.000000000 SOLs`,
+        amountToWithdraw: `${
+          withdrawRequestAmount / LAMPORTS_PER_SOL
+        }.000000000 SOLs`,
         withdrawRequest: {
           publicKey: withdrawRequestAccount.toBase58(),
           account: {
             voteAccount: withdrawRequestData.voteAccount.toBase58(),
             bond: bondAccount.toBase58(),
             epoch,
-            requestedAmount: withdrawRequestAmount,
-            withdrawnAmount: 0,
+            requestedAmount: `${
+              withdrawRequestAmount / LAMPORTS_PER_SOL
+            }.000000000 SOLs`,
+            withdrawnAmount: '0.000000000 SOL',
           },
         },
       }),
@@ -627,7 +633,9 @@ describe('Show command using CLI', () => {
       // stderr: '',
       stdout: YAML.stringify({
         ...expectedData,
-        amountActive: sumLamports,
+        amountActive: `${sumLamports / LAMPORTS_PER_SOL}.${
+          sumLamports % LAMPORTS_PER_SOL
+        }00000000 SOLs`,
       }),
     })
   })

packages/validator-bonds-cli/src/commands/manage/configureBond.ts

@@ -3,7 +3,12 @@ import {
   parsePubkeyOrPubkeyFromWallet,
   parseWalletOrPubkey,
 } from '@marinade.finance/cli-common'
-import { PublicKey, Signer, TransactionInstruction } from '@solana/web3.js'
+import {
+  LAMPORTS_PER_SOL,
+  PublicKey,
+  Signer,
+  TransactionInstruction,
+} from '@solana/web3.js'
 import { Command } from 'commander'
 import { setProgramIdByOwner } from '../../context'
 import {
@@ -62,12 +67,12 @@ export function installConfigureBond(program: Command) {
     )
     .option(
       '--cpmpe <number>',
-      'Nev value of cost per mille per epoch',
+      'New value of cost per mille per epoch, in lamports. The maximum amount of lamports the validator desires to pay for each 1000 delegated SOLs per epoch. (default: 0)',
       value => new BN(value, 10)
     )
     .option(
       '--max-stake-wanted <number>',
-      'New maximal value of stake for PSR bidding',
+      'New value of maximum stake amount, in SOLs, the validator wants to be delegated to them (default: 0)',
       value => new BN(value, 10)
     )
     .action(
@@ -160,6 +165,7 @@ async function manageConfigureBond({
   let bondAccount: PublicKey
   let instruction: TransactionInstruction
   let computeUnitLimit: number
+  const newMaxStakeWanted = maxStakeWanted?.mul(new BN(LAMPORTS_PER_SOL))
   if (withToken) {
     computeUnitLimit = CONFIGURE_BOND_MINT_LIMIT_UNITS
     ;({ instruction, bondAccount } = await configureBondWithMintInstruction({
@@ -170,7 +176,7 @@ async function manageConfigureBond({
       tokenAuthority: authority,
       newBondAuthority,
       newCpmpe: cpmpe,
-      newMaxStakeWanted: maxStakeWanted,
+      newMaxStakeWanted,
     }))
   } else {
     computeUnitLimit = CONFIGURE_BOND_LIMIT_UNITS
@@ -182,7 +188,7 @@ async function manageConfigureBond({
       authority,
       newBondAuthority,
       newCpmpe: cpmpe,
-      newMaxStakeWanted: maxStakeWanted,
+      newMaxStakeWanted,
     }))
   }
   tx.add(instruction)

packages/validator-bonds-cli/src/commands/manage/configureConfig.ts

@@ -73,7 +73,7 @@ export function installConfigureConfig(program: Command) {
     )
     .option(
       '--min-bond-max-stake-wanted <number>',
-      'New value of minimum for max-stake-wanted field configured by validators in bond.',
+      'New value of minimum for max-stake-wanted field, in lamports, configured by validators in bond.',
       value => new BN(value, 10)
     )
     .action(

packages/validator-bonds-cli/src/commands/manage/initBond.ts

@@ -17,7 +17,7 @@ import {
   initBondInstruction,
 } from '@marinade.finance/validator-bonds-sdk'
 import { Wallet as WalletInterface } from '@marinade.finance/web3js-common'
-import { PublicKey, Signer } from '@solana/web3.js'
+import { LAMPORTS_PER_SOL, PublicKey, Signer } from '@solana/web3.js'
 import { INIT_BOND_LIMIT_UNITS } from '../../computeUnits'
 import BN from 'bn.js'
 
@@ -56,12 +56,12 @@ export function installInitBond(program: Command) {
     )
     .option(
       '--cpmpe <number>',
-      'Cost per mille per epoch (default: 0)',
+      'Cost per mille per epoch, in lamports. The maximum amount of lamports the validator desires to pay for each 1000 delegated SOLs per epoch. (default: 0)',
       value => new BN(value, 10)
     )
     .option(
       '--max-stake-wanted <number>',
-      'Maximal value of stake for PSR bidding (default: 0)',
+      'The maximum stake amount, in SOL, that the validator wants to be delegated to them (default: 0).',
       value => new BN(value, 10)
     )
     .action(
@@ -152,7 +152,7 @@ async function manageInitBond({
     validatorIdentity,
     rentPayer,
     cpmpe,
-    maxStakeWanted,
+    maxStakeWanted: maxStakeWanted.mul(new BN(LAMPORTS_PER_SOL)),
   })
   tx.add(instruction)