Publish latest changes to prod

condor/transactions.md

@@ -2,8 +2,8 @@
 title: Transactions in Casper 2.0
 description: A discussion of the new Transaction data type
 slug: transactions
-date: 2024-10-03T18:00
-authors: [ asladeofgreen ]
+date: 2025-07-10T18:00
+authors: [ asladeofgreen, melpadden, devendranm ]
 tags: [v2, smartcontracts]
 hide_table_of_contents: false
 ---
@@ -18,28 +18,177 @@ In this article we will examine user transactions (previously called deploys).
 
 Transactions encapsulate user intents.  For example, if Alice intends to transfer CSPR to Bob, she uses software (e.g. a wallet) to construct and sign a transaction that is subsequently dispatched to a trusted node for processing by the network.
 
-Transactions may be either 'native' or 'custom':
+Transactions may be either 'native' or 'WASM':
 
-- Native transactions are those that interact with system contracts such as mint and/or auction.  They do not require any WASM payload to be constructed,  are normally compact in size, and are processed directly on the metal, i.e. host-side.
+- Native transactions are those that interact with system contracts such as `mint` and/or `auction`.  They do not require any Web Assembly(WASM) payload to be constructed,  are normally compact in size, and are processed directly on the metal, i.e. host-side.
 
-- Custom transactions are those that interact with the system via either on-chain smart contracts or in-line session logic.  All such interactions are based upon user-defined WASM binaries, and are executed within one of the node's supported virtual machines.
+- Web Assembly(WASM) transactions are those that interact with the system via either on-chain smart contracts or session logic.  All such interactions are based upon user-defined WASM binaries, and are executed within one of the node's supported virtual machines.
 
-In Casper 1.0 there was a single native transaction type (Transfer), and a set of custom transaction types (ContractByHash, ContractByHashVersioned, ContractByName, ContractByNameVersioned, ContractBytes). In Casper 2.0 the set of both native & custome transaction types have been expanded.
+In Casper 1.0 there was a single native transaction type (Transfer), and a set of WASM based transaction types (ContractByHash, ContractByHashVersioned, ContractByName, ContractByNameVersioned, ContractBytes). In Casper 2.0 the set of both native & WASM transaction types have been expanded.
 
 Casper 2.0 Native Transaction Types:
 
-- System.Mint.Transfer
-- System.Mint.Burn
-- System.Auction.Bid.Submit
-- System.Auction.Bid.Withdraw
-- System.Auction.Delegation.Redelegate
-- System.Auction.Delegation.Submit
-- System.Auction.Delegation.Withdraw
-- System.Auction.Staking.Submit
-- System.Auction.Staking.Withdraw
+|Type|Description|
+|--------|---------------------------------|
+| `add-bid` | To create a bid purse or or increase an existing bidder's bid amount |
+| `activate-bid` | To reactivate an inactive bid |
+| `withdraw-bid` | Used to decrease a validator's stake or remove their bid completely if the remaining stake is below the minimum required amount |
+| `delegate` | Used to add a new delegator or increase an existing delegator's stake |
+| `undelegate` | To reduce a delegator's stake or remove the delegator if the remaining stake is zero |
+| `redelegate` | To reduce a delegator's stake or remove the delegator if the remaining stake is zero. After the unbonding delay, it will automatically delegate to a new validator |
+| `transfer` | Used to reference motes from a source purse to a target purse |
 
 Not all work is identical, e.g. a base token (cspr) transfer differs from a smart contract execution.  
 
 Casper 1.0 supported a set of 6 transaction types, in Casper 2.0 the set is both refined and expanded.
 
-The Transaction stat type has a number of changes from its predecessor, the Deploy. For a detailed discussion of these differences you can see the casper documentation of this discussion of the JSON schema. 
+The Transaction type has a number of changes from its predecessor, the Deploy. 
+
+### Deploys and Transactions
+
+The Deploy model is deprecated as of Casper 2.0, and support will be removed entirely in a future major release. However, Casper 2.0 will continue to accept valid Deploys and will attempt to execute them. For more details on Transactions, please refer to the Documentation section [here](https://docs.casper.network/concepts/transactions). 
+
+## How to create a transaction
+
+A transaction, such as transferring CSPR tokens from one user's purse to another, can be created and sent to the Casper Network for processing using any of three methods:
+
+1. CSPR.Live
+2. SDK [e.g JavaScript/TypeScript SDK]
+3. Casper Client
+
+### 1. CSPR.Live
+
+You can transfer Casper tokens (CSPR) using any block explorer built to explore the Casper blockchain. The Wallet feature on these block explorers enables transfers to another user's purse, delegate stake, or undelegate stake.
+
+[CSPR.Live](https://cspr.live/) is the main and recommended Casper block explorer. For detailed guidance, the [**Transferring Tokens**](https://docs.casper.network/users/token-transfer#transferring-tokens-1) page in the **Users** section of the documentation provides step-by-step instructions on how to transfer CSPR tokens using CSPR.live.
+
+### 2. SDK
+
+The following example demonstrates how to create and execute a native CSPR token transfer using the JavaScript SDK.  This walkthrough shows the complete process of constructing, signing, and submitting a transaction to the Casper Network.
+
+#### 2.1. Initialize RPC client with network endpoint
+
+This is to establish connection to a Casper node endpoint for network communication.
+
+```js
+const rpcHandler = new HttpHandler(ENDPOINT);
+const rpcClient = new RpcClient(rpcHandler);
+```
+
+#### 2.2. Load sender's private key securely
+
+This is to load the sender's private key from a secure file location using Ed25519 cryptography.
+
+```js
+const privateKey = getPrivateKey_ed25519(PRIVATE_KEY_PATH);
+```
+
+#### 2.3. Build transaction
+
+Build transaction using `NativeTransferBuilder` with:
+- Sender and recipient addresses
+- Transfer amount (in motes: 1 CSPR = 1,000,000,000 motes)
+- Unique transaction ID
+- Network chain name
+- Gas payment amount
+
+**NOTE:** All amounts must be specified in motes (smallest CSPR unit)
+
+```js
+const transaction = new NativeTransferBuilder()
+  .from(privateKey.publicKey)           // Sender's public key
+  .target(PublicKey.fromHex('015ae...')) // Recipient's public key
+  .amount('2500000000')                 // 2.5 CSPR in motes
+  .id(Date.now())                       // Unique transaction ID
+  .chainName(NETWORKNAME)               // Network identifier
+  .payment(100_000_000)                 // Gas fee (0.1 CSPR)
+  .build();
+```
+
+
+#### 2.4. Sign transaction with private key
+
+The transaction built in the previous step is signed using the private key;
+
+```js
+transaction.sign(privateKey);
+```
+
+#### 2.5. Submit to network
+
+In this step, the constructed transaction is submitted to the network;
+
+```js
+try {
+  const result = await rpcClient.putTransaction(transaction);
+  console.log(Transaction Hash: ${result.transactionHash});
+} catch (e) {
+  console.error(e);
+}
+```
+
+
+#### 2.6. Receive transaction hash for tracking
+
+A transaction hash will be returned , which the user can use it to verify the transaction in the Block Explorer like CSPR.Live
+
+Below is a screenshot of an example Transfer [transaction](https://cspr.live/transaction/7ef02f29e9589b971615e79bb2325b1bffff144ede2137bb9366497b9fc9afb5) on the Mainnet;
+
+![CSPR Transfer example](./images/transfer_example.png)
+
+In this example transaction `7ef02f29e9589b971615e79bb2325b1bffff144ede2137bb9366497b9fc9afb5`, 49, 999.60 CSPR has been transferred from `020396133b3bbbfcf7d1961390f9449e2de5813523180376df361cb31a1ca965b576` to `020312d2d4c4cac436b4c9bd0dc7eba4d129bf5eb05e02f731f7a89221d2fde970c1`
+
+The "Raw Data" will give more details about the transaction.
+
+### 3. Casper Client
+
+A transaction can be initiated by using casper-client-rs CLI. Example V1 (2.0.0) and legacy transfers are given below with the clarity;
+
+#### V1 
+
+```sh
+# Casper CLI command to transfer CSPR tokens
+casper-client put-transaction transfer \
+--target 010068920746ecf5870e18911ee1fc5db975e0e97fffcbbf52f5045ad6c9838d2f \
+  # Recipient's public key (hexadecimal format)
+  --transfer-amount 2500000000 \                                                      # Amount to transfer: 2.5 CSPR (in motes)
+  --chain-name integration-test \                                                     # Network chain identifier , integration-test in this example
+  --gas-price-tolerance 1 \                                                          # Gas price tolerance (multiplier)
+  --secret-key path/to/secret_key.pem \                                 # Path to sender's private key file
+  --payment-amount 100000000 \                                                       # Gas fee: 0.1 CSPR (in motes)
+  --standard-payment true \                                                          # Use standard payment logic
+  -n http://node.integration.casper.network:7777/rpc                                 # Network RPC endpoint URL
+```
+
+
+#### Legacy
+
+```sh
+# Casper CLI command to transfer CSPR tokens (legacy)
+
+casper-client transfer \
+--amount 2500000000 \  # Amount to transfer: 2.5 CSPR (in motes)
+--target-account 010068920746ecf5870e18911ee1fc5db975e0e97fffcbbf52f5045ad6c9838d2f \  #Recipient's public key (hexadecimal format)
+--transfer-id 123 \  #Unique transfer identifier (prevents replay attacks)
+--secret-key path/to/secret_key.pem \  
+#Path to sender's private key file (PEM format)
+--chain-name integration-test \  #Network chain identifier , integration-test in this example
+  --payment-amount 100000000 \  #Gas fee: 0.1 CSPR (in motes)
+  -n http://node.integration.casper.network:7777/rpc 
+  # Network RPC endpoint URL
+```
+
+
+### Delegate and Undelegate Tokens
+
+CSPR token holders can earn rewards and participate in the protocol through a mechanism called delegation or [staking](https://docs.casper.network/concepts/economics/staking). 
+
+If a user wants to undelegate tokens from their chosen validator, they can do so at any time. 
+
+#### Delegate Tokens
+
+The tutorial [**Delegating Tokens with a Block Explorer**](https://docs.casper.network/users/delegate-ui) covers in detail how a user can delegate their tokens.
+
+#### Undelegate Tokens
+
+In order to undelegate their already delegated token, user can follow the step-by-step guide in the [**Undelegating Tokens**](https://docs.casper.network/users/undelegate-ui) section. 

config/sidebar.config.js

@@ -414,6 +414,18 @@ module.exports = {
                 //"resources/advanced/list-cspr",
             ],
         },
+        {
+            type: "category",
+            label: "Security Audit Reports",
+            collapsible: true,
+            collapsed: true,
+            link: {
+                type: "doc",
+                id: "resources/audit-reports/index",
+            },
+            items: [                
+            ],
+        },
     ],
     users: [
         "users/index",

docs/developers/dapps/setup-nctl.md

@@ -268,5 +268,5 @@ $ nctl-clean
 
 ## Next Steps {#next-steps}
 
-1.  Explore the [various NCTL commands](https://github.com/casper-network/casper-node/blob/master/utils/nctl/docs/commands.md).
-2.  Explore the [NCTL usage guide](https://github.com/casper-network/casper-node/blob/master/utils/nctl/docs/usage.md).
+1.  Explore the [various NCTL commands](https://github.com/casper-network/casper-nctl/blob/dev/docs/commands-ctl.md).
+2.  Explore the [NCTL usage guide](https://github.com/casper-network/casper-nctl/blob/dev/docs/usage.md).

docs/operators/becoming-a-validator/unbonding.md

@@ -6,7 +6,7 @@ title: Unbonding
 
 Once a bid is placed, it will remain in the state of the auction contract, even if the bid fails to win a slot immediately. New slots may become available if bonded validators leave the network or reduce their bond amounts. Therefore, a bid must be explicitly withdrawn to remove it from the auction.
 
-## Method 1: Unbonding with the System Auction Contract {#withdraw-system-auction}
+## Unbonding with the System Auction Contract {#withdraw-system-auction}
 
 This method withdraws a bid using the system auction contract. Call the existing `withdraw_bid` entry point from the system auction contract. Using this method, you do not need to build any contracts, reducing costs and complexity.
 
@@ -46,6 +46,39 @@ Calling the `withdraw_bid` entry point on the auction contract has a fixed cost
 
 :::
 
+## `withdraw-bid` Guardrails
+
+There are additional guardrails in place to ensure accidental full withdrawal/unstaking of the stakes.
+
+- `withdraw-bid` will check if the withdraw bid will not result in a Validator's stake dropping below the Validator minimum bid threshold. It will return an error if a Validator's staked amount will fall below the minimum bid amount for Validators when executing the transaction.
+- `withdraw-bid-all` is a sub-command that takes in a public key of a Validator and produces a withdraw bid transaction that will completely unbond the Validator.
+- A minimum-bid override flag `min-bid-override` is available for Validators to log a warning to the standard output and produce/send the withdraw bid transaction.
+- The withdraw-bid guardrails have been extended to `put-transaction` and `put-deploy` subcommands that invoke the entry point via stored contract by hash/name and package by hash/name.
+
+**Guardrails Example :**
+
+| Case         | Stake Scenario       | Transaction       | Result |
+|--------------|----------------------|-------------------|--------|
+| **When the withdraw-bid transaction will result in remaining stake falling below the minimum bid threshold - i.e. <10,000,000,000,000 motes** | <br/>Staked: 17,536,609,871,045 motes<br/><br/>Withdraw: 17,536,609,871,045 motes <br/><br/>Remaining Stake: 0 motes | `withdraw-bid` <br/>without<br/>`--min-bid-override` | Client guardrail prevents execution with <br/>"**Attempting to withdraw bid will reduce stake below the minimum amount.**" error |
+| **When the withdraw-bid transaction will result in remaining stake being equal to or over the minimum bid threshold - i.e. >=10,000,000,000,000 motes** | <br/>Staked: 17,536,609,871,045 motes<br/><br/>Withdraw: 7,536,609,871,045 motes <br/><br/>Remaining Stake: 10,000,000,000,000 motes | `withdraw-bid` <br/>without<br/>`--min-bid-override` | Transaction will execute successfully |
+| **When the withdraw-bid transaction with min-bid-override flag will result in remaining stake being less than minimum bid threshold - i.e. <10,000,000,000,000 motes** | <br/>Before: 17,536,609,871,045 motes<br/><br/>Withdraw: 17,536,609,871,044 motes | `withdraw-bid` <br/>with<br/>`--min-bid-override` | Transaction will execute with a warning `Execution of this withdraw bid will result in unbonding of all stake` |
+| **When the withdraw-bid transaction with min-bid-override flag will result in remaining stake being equal to or greater than minimum bid threshold - i.e. >=10,000,000,000,000 motes** | <br/>Before: 17,536,609,871,045 motes<br/><br/>Withdraw: 7,536,609,871,044 motes | `withdraw-bid` <br/>with<br/>`--min-bid-override` | Transaction will execute successfully |
+
+**How to use the `min-bid-override` flag in a transaction?**
+
+Example transaction with `min-bid-override` flag:
+```bash
+casper-client put-transaction withdraw-bid \
+--public-key 01733fe8a5d57837e404fb994da618d8a1757c9b8290fb331db28b9df61423f038 \
+--transaction-amount  119999596675466 \
+--min-bid-override \
+--chain-name casper-test \
+ --secret-key /etc/casper/validator_keys/secret_key.pem \
+ --standard-payment true \
+ --gas-price-tolerance 1 \
+--payment-amount 2500000000
+```
+
 **Example:**
 
 This example command uses the Casper Testnet to withdraw 5 CSPR from the bid:
@@ -76,55 +109,6 @@ sudo -u casper casper-client put-deploy \
 --session-arg "amount:U512='$[5 * 1000000000]'"
 ```
 
-## Method 2: Unbonding with Compiled Wasm {#withdraw-compiled-wasm}
-
-There is a second way to withdraw a bid, using the compiled Wasm `withdraw_bid.wasm`. The process is the same as bonding but uses a different contract.
-
-```bash
-sudo -u casper casper-client put-deploy \
---node-address <HOST:PORT> \
---secret-key <PATH> \
---chain-name <CHAIN_NAME> \
---payment-amount <PAYMENT_AMOUNT> \
---session-path <PATH>/casper-node/target/wasm32-unknown-unknown/release/withdraw_bid.wasm \
---session-arg="public_key:public_key='<PUBLIC_KEY_HEX>'" \
---session-arg="amount:u512='<AMOUNT_TO_WITHDRAW>'"
-```
-
-1. `node-address` - An IP address of a peer on the network. The default port of nodes' JSON-RPC servers on Mainnet and Testnet is 7777
-2. `secret-key` - The file name containing the secret key of the account paying for the Deploy
-3. `chain-name` - The chain-name to the network where you wish to send the Deploy. For Mainnet, use *casper*. For Testnet, use *casper-test*
-4. `payment-amount` - The payment for the Deploy in motes estimated
-5. `session-path` - The path to the compiled Wasm on your computer
-
-The `withdraw_bid.wasm` expects two arguments, while the third one is optional:
-
-6. `public key`: The hexadecimal public key of the account's purse to withdraw. This key must match the secret key that signs the deploy and has to match the public key of a bid in the auction contract
-7. `amount`: The amount being withdrawn
-
-The command will return a deploy hash, which is needed to verify the deploy's processing results.
-
-:::note
-
-This method is more expensive than calling the `withdraw_bid` entrypoint in the system auction contract, which has a fixed cost of 2.5 CSPR.
-
-:::
-
-**Example:**
-
-Here is an example request to unbond stake using the `withdraw_bid.wasm`. The payment amount specified is 4 CSPR. You must modify the payment and other values in the deploy based on the network's [chainspec.toml](../../concepts/glossary/C.md#chainspec).
-
-```bash
-sudo -u casper casper-client put-deploy \
---node-address http://65.21.75.254:7777 \
---secret-key /etc/casper/validator_keys/secret_key.pem \
---chain-name casper-test \
---session-path $HOME/casper-node/target/wasm32-unknown-unknown/release/withdraw_bid.wasm \
---payment-amount 4000000000 \
---session-arg="public_key:public_key='01c297d2931fec7e22b2fb1ae3ca5afdfacc2c82ba501e8ed158eecef82b4dcdee'" \
---session-arg="amount:u512='1000000000000'"
-```
-
 
 ## Check the Auction Contract {#check-the-auction-contract}