diff --git a/condor/images/transfer_example.png b/condor/images/transfer_example.png new file mode 100644 index 000000000..87ee44f12 Binary files /dev/null and b/condor/images/transfer_example.png differ diff --git a/condor/transactions.md b/condor/transactions.md index e11bc4571..d5b35b31d 100644 --- a/condor/transactions.md +++ b/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. \ No newline at end of file diff --git a/config/sidebar.config.js b/config/sidebar.config.js index 890421b69..f327fc1f4 100644 --- a/config/sidebar.config.js +++ b/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", diff --git a/docs/developers/dapps/setup-nctl.md b/docs/developers/dapps/setup-nctl.md index 59c3d4c41..4459161c4 100644 --- a/docs/developers/dapps/setup-nctl.md +++ b/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). diff --git a/docs/operators/becoming-a-validator/unbonding.md b/docs/operators/becoming-a-validator/unbonding.md index 84a51f6fb..0ca8f2971 100644 --- a/docs/operators/becoming-a-validator/unbonding.md +++ b/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** |
Staked: 17,536,609,871,045 motes

Withdraw: 17,536,609,871,045 motes

Remaining Stake: 0 motes | `withdraw-bid`
without
`--min-bid-override` | Client guardrail prevents execution with
"**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** |
Staked: 17,536,609,871,045 motes

Withdraw: 7,536,609,871,045 motes

Remaining Stake: 10,000,000,000,000 motes | `withdraw-bid`
without
`--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** |
Before: 17,536,609,871,045 motes

Withdraw: 17,536,609,871,044 motes | `withdraw-bid`
with
`--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** |
Before: 17,536,609,871,045 motes

Withdraw: 7,536,609,871,044 motes | `withdraw-bid`
with
`--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 \ ---secret-key \ ---chain-name \ ---payment-amount \ ---session-path /casper-node/target/wasm32-unknown-unknown/release/withdraw_bid.wasm \ ---session-arg="public_key:public_key=''" \ ---session-arg="amount:u512=''" -``` - -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} diff --git a/docs/resources/audit-reports/index.md b/docs/resources/audit-reports/index.md new file mode 100644 index 000000000..d77920ed1 --- /dev/null +++ b/docs/resources/audit-reports/index.md @@ -0,0 +1,53 @@ +# Casper Network Security Audit Reports + +Welcome to Casper Network's official security audit documentation. + +Our security audit program encompasses both core network infrastructure and ecosystem projects, ensuring comprehensive coverage across the entire Casper Network landscape. + +## Purpose +This page serves as your central hub for accessing security audit reports across the Casper Network ecosystem, by consolidating and sharing security audit reports to promote transparency and enable the ecosystem to make informed decisions about project security. + +## Report Format + +The standardized audit reports provide comprehensive insights into security assessments: + +**Executive Summary** A high-level overview of key findings, risk assessments, and overall security posture suitable for technical and non-technical stakeholders. + +**Audit Scope and Methodology** Detailed information about what was assessed, testing approaches used, and the audit framework applied to ensure thorough coverage. + +**Findings and Recommendations** Complete documentation of identified vulnerabilities, security improvements, and actionable recommendations categorized by severity level. + +**Remediation Status** Current status of addressed findings, implementation timelines, and verification of fixes where applicable. + +**Auditor Information** Details about the auditing firm, their credentials, expertise areas, and methodology standards to help you assess report credibility. + +## Audit Information + +| Project | Prepared by | Report Date/Last Updated | Remediation Status | Full Report | +|---------|-------------|--------------|---------------------|-------------| +| Bridge Contracts | HALBORN | 07/17/2024 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper---allbridge-fa8c33) | +| Shiboo Token - Simplified | HALBORN | 08/21/2024 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper---shiboo-token---simplified-assessment-70b767) | +| Casper 2.0 - Casper Association | HALBORN | 04/17/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper-20-12a8fb) | +| Odra - Liquid Staking | HALBORN | 05/27/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/odra---liquid-staking-231379) | +| MAKE CSPR.name | HALBORN | 07/03/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/make-csprname-7b1108) | +| CEP18 | HALBORN | 07/21/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/cep18-799d0b) | + + + +## Important Notice + +Security audit reports represent findings at the specific time of assessment. The dynamic nature of software development means that: + +Projects may have implemented security fixes and updates since the original audit date +New features or modifications may have been introduced that weren't part of the original scope +We recommend verifying the current security status directly with project teams before making integration decisions + +For the most current security information, we encourage you to review the latest available reports and contact project maintainers for recent updates. + +## Continuous Security Improvement + +This documentation represents our ongoing commitment to security excellence. We regularly update our audit repository with new reports and maintain current remediation status information to ensure the community has access to the most accurate and up-to-date security intelligence. + +## Contact + +For questions about submissions or repository access, please open an issue or contact the Casper Network team through our official support channels for detailed discussions about findings or methodologies. \ No newline at end of file diff --git a/versioned_docs/version-2.0.0/concepts/serialization/calltable-serialization.md b/versioned_docs/version-2.0.0/concepts/serialization/calltable-serialization.md index 2ccf167bb..d65d84667 100644 --- a/versioned_docs/version-2.0.0/concepts/serialization/calltable-serialization.md +++ b/versioned_docs/version-2.0.0/concepts/serialization/calltable-serialization.md @@ -9,7 +9,7 @@ As mentioned before, the `calltable serialization approach` requires serializing - `fields` - field which is an ordered collection of [Field](#field). This collection is serialized as a Vec<Field> in the "regular" `Binary Serialization Standard` schema. The invariants for `fields` are: - for each fi, fj given `i` < `j` implies fi.index < fj.index - for each fi, fj given `i` < `j` implies fi.offset < fj.offset -- `bytes` - field which is an amorphous blob of bytes serialized as `Bytes` in the "regular" `Binary Serialization Standard` schema. +- `bytes` - field which is an amorphous blob of bytes serialized as `Bytes` in the "regular" `Binary Serialization Standard` schema. Bear in mind that this field will be serialized by appending first a `u32` integer (number of bytes) than the raw bytes payload. A `Field` consists of: @@ -79,6 +79,9 @@ Once we have the `fields` and `bytes` we can proceed to serialize those in the " for i in range(0, len(fields)): bytes_arr += fields[i]["index"].to_bytes(2, byteorder = 'little') bytes_arr += fields[i]["offset"].to_bytes(4, byteorder = 'little') + concatenated_serialized_fields_len = len(concatenated_serialized_fields) + print(f"{concatenated_serialized_fields_len}") + bytes_arr += concatenated_serialized_fields_len.to_bytes(4, byteorder = 'little') bytes_arr += concatenated_serialized_fields return bytes_arr ``` @@ -88,7 +91,7 @@ and once we have all that we can apply the scripts to example: ```python I = [0, 1, 3, 5] B = [bytes([0, 1, 255]), bytes([55, 12, 110, 60, 15]), bytes([7, 149, 1]), bytes([55])] - envelope = buildCalltableData(I, B) + envelope = build_calltable_data(I, B) serialized_calltable_representation = serialize_calltable_representation(envelope["fields"], envelope["bytes"]) print(f"{serialized_calltable_representation.hex()}") ``` @@ -96,15 +99,15 @@ and once we have all that we can apply the scripts to example: which produces: ``` -0400000000000000000001000300000003000800000005000b0000000001ff370c6e3c0f07950137 +0400000000000000000001000300000003000800000005000b0000000c0000000001ff370c6e3c0f07950137 ``` In the above hex: -| Serialized length of `fields` collection | field[0].index | field[0].offset | field[1].index | field[1].offset | field[2].index | field[2].offset | field[3].index | field[3].offset | bytes | -| ---------------------------------------- | -------------- | --------------- | -------------- | --------------- | -------------- | --------------- | -------------- | --------------- | ----- | -| 04000000 | 0000 | 00000000 | 0100 | 03000000 | 0300 | 08000000 | 0500 | 0b000000 | 0001ff370c6e3c0f07950137 +| Serialized length of `fields` collection | field[0].index | field[0].offset | field[1].index | field[1].offset | field[2].index | field[2].offset | field[3].index | field[3].offset | number of bytes in `bytes` field | raw bytes of `bytes` field | +| ---------------------------------------- | -------------- | --------------- | -------------- | --------------- | -------------- | --------------- | -------------- | --------------- | ----- | -- | +| 04000000 | 0000 | 00000000 | 0100 | 03000000 | 0300 | 08000000 | 0500 | 0b000000 | 0c000000 | 0001ff370c6e3c0f07950137 -This concludes how we construct and byte-serialize an `envelope`. In the next paragraphs we will explain what are the assumptions and conventions when dealing with `struct`s and `enum`s. +This concludes how we construct and byte-serialize an `envelope`. In the next paragraphs we will explain what are the assumptions and conventions when dealing with `struct`s and `tagged-union`s. ## Serializing uniform data structures @@ -120,15 +123,15 @@ struct A { In the above example we could assign `a` index `0`, `b` index `1` and `c` index `2`. Knowing this and assuming that we know how to byte-serialize `OtherStruct` we should be able to create an `envelope` for this struct and serialize it in the `calltable` scheme. -## Serializing enums +## Serializing tagged-unions -By `enums` we understand polymorphic, but limited (an instance of an enum can be only one of N known `variants`) data structures that are unions of structures and/or other enums. An enum variant can be: +By `tagged-union` we understand polymorphic, but limited (an instance of an tagged-union can be only one of N known `variants`) data structures that are unions of structures and/or other tagged-unions. An tagged-union variant can be: - empty (tag variant) - a struct -- a nested enum +- a nested tagged-union -As mentioned, there is a polymorphic aspect to these kinds of enums and we handle them by convention - `serialization index` `0` is always reserved for a 1 byte discriminator number which defines which enum variant is being serialized, the next indices are used to serialize the fields of specific variants (for empty tag variants there will be no more indices). So, given an enum: +As mentioned, there is a polymorphic aspect to these kinds of tagged-union and we handle them by convention - `serialization index` `0` is always reserved for a 1 byte discriminator number which defines which tagged-union variant is being serialized. The value of this specific pseudo-field will be called `variant discriminator`. Subsequent indices are used to serialize the fields of specific variants (for empty tag variants there will be no more indices). So, given an example tagged-union (implemented in rust, rust equivalent of tagged-union is `enum`): ```rust enum X { @@ -138,13 +141,13 @@ As mentioned, there is a polymorphic aspect to these kinds of enums and we handl } ``` -First we need to chose variant discriminator values for each of the enum variants, let's select: +First we need to chose variant discriminator values for each of the tagged-union variants, let's select: - if variant `A` - the variant discriminator will be `0` - if variant `B` - the variant discriminator will be `1` - if variant `C` - the variant discriminator will be `2` -Again, as with fields in `Serializing enums` the variant discriminator values don't need to start from `0` and don't need to be contiguous, but that is our convention and any "holes" in the definition would indicate a retired enum variant. +Again, as with fields in `Serializing tagged-unions` the variant discriminator values does not need to start from `0` and does not need to be contiguous, but that is our convention and any "discontinuities" in the value set for variant disciminator would indicate a retired tagged-union variant or variants. Next we need to assign field `serialization indices` for each variant: @@ -157,8 +160,8 @@ Next we need to assign field `serialization indices` for each variant: - `2` for the second tuple element (of type u32), - `3` for the second tuple element (of type u64), -As you can see, `serialization indices` for fields need to be unique in scope of a particular enum variant. -Knowing the above, let's see how the `I` and `B` collections would look like for different instances of this enum: +As you can see, `serialization indices` for fields need to be unique in scope of a particular tagged-union variant. +Knowing the above, let's see how the `I` and `B` collections would look like for different instances of this tagged-union: - when serializing variant `X::A` (assuming python notation): ```python diff --git a/versioned_docs/version-2.0.0/concepts/serialization/transaction-deserialization-example.md b/versioned_docs/version-2.0.0/concepts/serialization/transaction-deserialization-example.md new file mode 100644 index 000000000..33ec19208 --- /dev/null +++ b/versioned_docs/version-2.0.0/concepts/serialization/transaction-deserialization-example.md @@ -0,0 +1,386 @@ +# Transaction deserialization example + +``` +**PLEASE NOTE** In this document long snippets representing hex-encoded bytes are split into 64 character lines. Putting such a text in multiple lines does not mean that the newline character is part of the binary payload - newlines are used purely as formatting. +``` + +In this document we will go through byte-deserialization of a full Transaction example. We will assume an examble binary payload and we will step-by-step deserialize it. The goal here is to show a real-life example of how calltable serialization works. To achieve that we will have a Transaction::Version1 variant since Transaction::Deploy doesn't use calltable serialization. + +Here is an example hex-encoded byte array payload: + +``` +0x01030000000000000000000100200000000200170100007d01000013891c67 +a803d1803c932c6a9c342a44e8adb7be3f287cd69a8cab8b2a446fa606000000 +00000000000001003600000002003e0000000300460000000400520000000500 +7d000000cb00000002000000000000000000010001000000220000000001d9bf +2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c7b00 +00000000000080ee360000000000080000006d792d636861696e040000000000 +0000000001000100000002000900000003000a0000000b0000000053aa080000 +000000010104000000000005000000000000000001000f000000010000000000 +00000000010000000002000f0000000100000000000000000001000000050300 +0f0000000100000000000000000001000000000100000001d9bf2148748a85c8 +9da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c013104d575cdd9a8 +65a54eae377586dd2ea9912fde9511d3471f63a73c1162b7f6c7a290611a527f +c14247e4eb86c308c27f45d2ece4abc506291c600c54ee720b +``` + +## Deserializing Transaction + +The first byte of the payload is `01`, by which we know that we need to attempt to treat it as a Transaction::Version1. We will drop the first byte and proceed deserializing the rest as `TransactionV1` - since that is the internal payload of Transaction::Version1 + +## Deserializing TransactionV1 + +After unpacking the discriminator byte for `Transaction` we are left with the following bytes: + +``` +0x030000000000000000000100200000000200170100007d01000013891c67a8 +03d1803c932c6a9c342a44e8adb7be3f287cd69a8cab8b2a446fa60600000000 +000000000001003600000002003e00000003004600000004005200000005007d +000000cb00000002000000000000000000010001000000220000000001d9bf21 +48748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c7b0000 +000000000080ee360000000000080000006d792d636861696e04000000000000 +00000001000100000002000900000003000a0000000b0000000053aa08000000 +0000010104000000000005000000000000000001000f00000001000000000000 +000000010000000002000f00000001000000000000000000010000000503000f +0000000100000000000000000001000000000100000001d9bf2148748a85c89d +a5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c013104d575cdd9a865 +a54eae377586dd2ea9912fde9511d3471f63a73c1162b7f6c7a290611a527fc1 +4247e4eb86c308c27f45d2ece4abc506291c600c54ee720b +``` + +TransactionV1 is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x03000000 | le-encoded number of entries in the calltable header for TransactionV1 | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means `hash` | +| 0x00000000 | le encoded `offset` of the first calltable entry | +| 0x0100 | le encoded `index` of the second calltable entry: `1` means `payload` | +| 0x20000000 | le encoded `offset` of the second calltable entry: `32` means that the bytes of `payload` start at byte 32 of the binary payload of the calltable envelope | +| 0x0200 | le encoded `index` of the third calltable entry: `2` means `approvals` | +| 0x17010000 | le encoded `offset` of the third calltable entry: `279` means that the bytes of `payload` start at byte 279 of the binary payload of the calltable envelope | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| 0x7d010000 | 381 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x13891c67a803d1803c932c6a9c342a44e8adb7be3f287cd69a8cab8b2a446fa6 | `hash` field of type Digest, should be interpreted as [here](./types.md#digest-digest) | +| 0x0600000000000000000001003600000002003e000000030046000000040052
00000005007d000000cb00000002000000000000000000010001000000220000
000001d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0a
e2900c7b0000000000000080ee360000000000080000006d792d636861696e04
00000000000000000001000100000002000900000003000a0000000b00000000
53aa080000000000010104000000000005000000000000000001000f00000001
000000000000000000010000000002000f000000010000000000000000000100
00000503000f000000010000000000000000000100000000 | binary representation of `payload` deserialization drill-down [here](#payload-field-deserialization) | +| 0x0100000001d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536
354f0ae2900c013104d575cdd9a865a54eae377586dd2ea9912fde9511d3471f
63a73c1162b7f6c7a290611a527fc14247e4eb86c308c27f45d2ece4abc50629
1c600c54ee720b | binary representation of a collection [Approvals](#deserializing-approvals) | + +### `payload` field deserialization + +Previously we established that the `payload` fields raw bytes are: + +``` +0x0600000000000000000001003600000002003e000000030046000000040052 +00000005007d000000cb00000002000000000000000000010001000000220000 +000001d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0a +e2900c7b0000000000000080ee360000000000080000006d792d636861696e04 +00000000000000000001000100000002000900000003000a0000000b00000000 +53aa080000000000010104000000000005000000000000000001000f00000001 +000000000000000000010000000002000f000000010000000000000000000100 +00000503000f000000010000000000000000000100000000 +``` + +now we will attempt to deserialize it as an instance of `TransactionV1Payload`. + +TransactionV1Payload is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| 0x06000000 | le-encoded number of entries in the calltable header for TransactionV1Payload | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means `initiator_addr` | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the initiator_addr starts at index 0 of the envelope payload | +| 0x0100 | le encoded `index` of the second calltable entry: `1` means `timestamp` | +| 0x36000000 | le encoded `offset` of the second calltable entry - means that the timestamp starts at index 54 of the envelope payload | +| 0x0200 | le encoded `index` of the third calltable entry: `2` means `ttl` | +| 0x3e000000 | le encoded `offset` of the third calltable entry - means that the ttl starts at index 62 of the envelope payload | +| 0x0300 | le encoded `index` of the fourth calltable entry: `3` means `chain_name` | +| 0x46000000 | le encoded `offset` of the fourth calltable entry - means that the chain_name starts at index 70 of the envelope payload | +| 0x0400 | le encoded `index` of the fifth calltable entry: `4` means `pricing_mode` | +| 0x52000000 | le encoded `offset` of the fifth calltable entry - means that the pricing_mode starts at index 82 of the envelope payload | +| 0x0500 | le encoded `index` of the sixth calltable entry: `5` means `fields` | +| 0x7d000000 | le encoded `offset` of the sixth calltable entry - means that the fields starts at index 125 of the envelope payload | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 0xcb000000  | 203 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x02000000000000000000010001000000220000000001d9bf2148748a85c89d
a5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c | bytes which should be interpreted as `InitiatorAddr` | +| 0x7b00000000000000 | bytes which should be interpreted as `Timestamp` (le unsigned 8 bytes unix-style milliseconds value which translates to `123`) | +| 0x80ee360000000000 | bytes which should be interpreted as `TTL` (le unsigned 8 bytes value which translates to `3600000`) | +| 0x080000006d792d636861696e | bytes which should be interpreted as [`String`](./primitives.md#string-clvalue-string) | +| 0x0400000000000000000001000100000002000900000003000a0000000b0000
000053aa0800000000000101 | bytes which should be interpreted as `PricingMode` | +| 0x04000000000005000000000000000001000f00000001000000000000000000
010000000002000f00000001000000000000000000010000000503000f000000
010000000000000000000100000000 | bytes which should be interpreted as a map of field id -> field mapping. Please see [this paragraph](#payloadfields-field-deserialization) for details | + +### `payload.initiator_addr` field deserialization + +Previously we established that the `initiator_addr` fields raw bytes were: + +``` +0x02000000000000000000010001000000220000000001d9bf2148748a85c89 +da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c +``` + +now we will attempt to deserialize it as an instance of `InitiatorAddr`. + +InitiatorAddr is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x02000000 | le-encoded number of entries in the calltable header for InitiatorAddr | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means variant discriminator of the union type (since InitiatorAddr is a union type) | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the variant discriminator starts at byte 0 of the envelope payload. | +| 0x0100 | le encoded `index` of the second calltable entry: `1` - we don't really know what field it is at this moment since we don't know what the variant is | +| 0x01000000 | le encoded `offset` of the second calltable entry - means that the payload of the first field of the strucure starts at position 1 of the envelope payload | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x22000000 | 34 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x00 | value of the discriminator - deserializes to `PublicKey` variant. We now know that `index = 1` from the header points to an instance of `PublicKey` | +| 0x01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2
900c | `PublicKey` whish should be interpreted as [`explained here`](./types.md#publickey-publickey) | + +### `payload.pricing_mode` field deserialization + +Previously we established that the `pricing_mode` fields raw bytes were: + +``` +0x0400000000000000000001000100000002000900000003000a0000000b000 +0000053aa0800000000000101 +``` + +now we will attempt to deserialize it as an instance of `PricingMode`. + +PricingMode is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x04000000 | le-encoded number of entries in the calltable header for PricingMode | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means variant discriminator of the union type (since PricingMode is a union type) | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the variant discriminator starts at byte 0 of the envelope payload. | +| 0x0100 | le encoded `index` of the second calltable entry: `1` - we don't really know what field it is at this moment since we don't know what the variant is | +| 0x01000000 | le encoded `offset` of the second calltable entry - means that the payload of the first field of the strucure starts at index 1 of the envelope payload | +| 0x0200 | le encoded `index` of the third calltable entry: `2` - we don't really know what field it is at this moment since we don't know what the variant is | +| 0x09000000 | le encoded `offset` of the third calltable entry - means that the payload of the second field of the strucure starts at index 9 of the envelope payload | +| 0x0300 | le encoded `index` of the fourth calltable entry: `3` - we don't really know what field it is at this moment since we don't know what the variant is | +| 0x0a000000 | le encoded `offset` of the fourth calltable entry - means that the payload of the second field of the strucure starts at index 10 of the envelope payload | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x0b000000 | 11 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x00 | value of the discriminator - deserializes to `PaymentLimited` variant. We now know that: `index = 1` from the header points to a 8 bytes unsigned number `payment_amount` field; `index = 2` from the header points to a 1 byte unsigned number `gas_price_tolerance` field; `index = 3` from the header points to a 1 byte bool `standard_payment` field | +| 0x53aa080000000000 | 567891 (8-bytes unsigned LE `payment_amount` ) | +| 0x01 | 1 (1-bytes unsigned LE) `gas_price_tolerance` | +| 0x01 | true `standard_payment` | + +### `payload.fields` field deserialization + +Previously we established that the `fields` fields raw bytes were: + +``` +0x04000000000005000000000000000001000f00000001000000000000000000 +010000000002000f00000001000000000000000000010000000503000f000000 +010000000000000000000100000000 +``` + +Payload of this field is not serialized using calltable. It is serialized as a map (for details, see [here](#version1payloadfields)). We will attempt to deconstruct the payload: + +| hex formatted bytes | Interpretation | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x04000000 | `4` - number of entries in the map (4 bytes LE encoded unsigned number) | +| 0x0000 | `0` - key of first entry (2 bytes encoded unsigned number) | +| 0x05000000 | `5` - number of bytes of the payload of the value under key `0` (4 bytes encoded unsigned number) | +| 0x0000000000 | 5 bytes read which is the raw payload for key `0`. Based on the fields index table [here](#version1payloadfields) we see that it should be interpreted as `TransactionArgs`. To deserialize `TransactionArgs` see [here](./types.md#transactionargs-transaction-args) | +| 0x0100 | `1` - key of second entry (2 bytes encoded unsigned number) | +| 0x0f000000 | `15` - number of bytes of the payload of the value under key `1` (4 bytes encoded unsigned number) | +| 0x010000000000000000000100000000 | 15 bytes read which is the raw payload for key `1`. Based on the fields index table [here](#version1payloadfields) we see that it should be interpreted as `TransactionTarget`. Deserialization explanation is [here](#payloadfields1-field-deserialization) | +| 0x0200 | `2` - key of third entry (2 bytes encoded unsigned number) | +| 0x0f000000 | `15` - number of bytes of the payload of the value under key `2` (4 bytes encoded unsigned number) | +| 0x010000000000000000000100000005 | 15 bytes read which is the raw payload for key `2`. Based on the fields index table [here](#version1payloadfields) we see that it should be interpreted as `TransactionEntryPoint`. Deserialization explanation is [here](#payloadfields2-field-deserialization) | +| 0x0300 | `3` - key of third entry (2 bytes encoded unsigned number) | +| 0x0f000000 | `15` - number of bytes of the payload of the value under key `2` (4 bytes encoded unsigned number) | +| 0x010000000000000000000100000000 | 15 bytes read which is the raw payload for key `2`. Based on the fields index table [here](#version1payloadfields) we see that it should be interpreted as `TransactionScheduling`. Deserialization explanation is [here](#payloadfields3-field-deserialization) | + +### `payload.fields.1` field deserialization + +Previously we established that the TransactionTarget fields map entry raw bytes are: + +``` +0x010000000000000000000100000000 +``` + +TransactionTarget is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| 0x01000000 | le-encoded number of entries in the calltable header for TransactionTarget | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means variant discriminator of the union type (since PricingMode is a union type) | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the variant discriminator starts at byte 0 of the envelope payload. | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | --------------------------------------------------------------------------------------------- | +| 0x01000000 | 1 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x00 | `0` value of the discriminator - deserializes to `Native` variant. This variant has no fields | + +### `payload.fields.2` field deserialization + +Previously we established that the TransactionEntryPoint fields map entry raw bytes are: + +``` +0x010000000000000000000100000005 +``` + +TransactionEntryPoint is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| 0x01000000 | le-encoded number of entries in the calltable header for TransactionEntryPoint | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means variant discriminator of the union type (since TransactionEntryPoint is a union type) | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the variant discriminator starts at byte 0 of the envelope payload. | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ----------------------------------------------------------------------------------------------- | +| 0x01000000 | 1 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x05 | `5` value of the discriminator - deserializes to `Delegate` variant. This variant has no fields | + +### `payload.fields.3` field deserialization + +Previously we established that the TransactionScheduling fields map entry raw bytes are: + +``` +0x010000000000000000000100000000 +``` + +TransactionScheduling is serialized using calltable representation. From the [calltable serialization](./calltable-serialization.md) document we know that we need to split the bytes into a header and payload: + +Interpretation of the bytes representing header of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| 0x01000000 | le-encoded number of entries in the calltable header for TransactionScheduling | +| 0x0000 | le encoded `index` of the first calltable entry: `0` means variant discriminator of the union type (since TransactionScheduling is a union type) | +| 0x00000000 | le encoded `offset` of the first calltable entry - means that the variant discriminator starts at byte 0 of the envelope payload. | + +Interpretation of the bytes representing payload of the calltable envelope: + +| hex formatted bytes | Interpretation | +| ------------------- | ----------------------------------------------------------------------------------------------- | +| 0x01000000 | 1 (4-bytes unsigned LE) - number of bytes in the paylod | +| 0x00 | `0` value of the discriminator - deserializes to `Standard` variant. This variant has no fields | + +### deserializing Approvals + +Previously we established that the `approvals` raw bytes are: + +``` +0x0100000001d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536 +354f0ae2900c013104d575cdd9a865a54eae377586dd2ea9912fde9511d3471f +63a73c1162b7f6c7a290611a527fc14247e4eb86c308c27f45d2ece4abc50629 +1c600c54ee720b +``` + +We can deserialize the above as [collection](./primitives.md#clvalue-list) of [approvals](./types.md#approval-approval) + +## Helper script + +The binary payload used in this example can be reproduced using the following script written in rust and facilitating the reference implementation [casper-types](https://crates.io/crates/casper-types) library. + +```rust + use casper_types::{ + Approval, Digest, InitiatorAddr, PricingMode, PublicKey, RuntimeArgs, SecretKey, TimeDiff, + Timestamp, Transaction, TransactionArgs, TransactionEntryPoint, TransactionHash, + TransactionScheduling, TransactionTarget, TransactionV1, TransactionV1Hash, + TransactionV1Payload, bytesrepr::ToBytes, + }; + use std::collections::{BTreeMap, BTreeSet}; + + let signer_secret_key = + SecretKey::ed25519_from_bytes([15u8; SecretKey::ED25519_LENGTH]).unwrap(); + let signer_public_key = PublicKey::from(&signer_secret_key); + let timestamp = Timestamp::from(123); + let ttl = TimeDiff::from_seconds(3600); + let pricing_mode = PricingMode::PaymentLimited { + payment_amount: 567_891_u64, + gas_price_tolerance: 1, + standard_payment: true, + }; + let initiator_addr = InitiatorAddr::PublicKey(signer_public_key); + let mut fields = BTreeMap::new(); + + let arg = TransactionArgs::Named(RuntimeArgs::new()); + let arg_bytes = arg + .to_bytes() + .expect("should be able to serialize transaction args to bytes"); + fields.insert(0_u16, arg_bytes.into()); + + let transaction_target = TransactionTarget::Native; + let target_bytes = transaction_target + .to_bytes() + .expect("should be able to serialize transaction_target to bytes"); + fields.insert(1_u16, target_bytes.into()); + + let entry_point = TransactionEntryPoint::Delegate; + let entry_point_bytes = entry_point + .to_bytes() + .expect("should be able to serialize entry_point to bytes"); + fields.insert(2_u16, entry_point_bytes.into()); + + let scheduling = TransactionScheduling::Standard; + let scheduling_bytes = scheduling + .to_bytes() + .expect("should be able to serialize scheduling to bytes"); + fields.insert(3_u16, scheduling_bytes.into()); + + let payload = TransactionV1Payload::new( + "my-chain".to_owned(), + timestamp, + ttl, + pricing_mode, + initiator_addr, + fields, + ); + let payload_bytes = payload + .to_bytes() + .expect("It should be possible to turn payload into bytes"); + let hash = Digest::hash(payload_bytes); + let approval = Approval::create( + &TransactionHash::V1(TransactionV1Hash::from(hash)), + &signer_secret_key, + ); + let mut approvals = BTreeSet::new(); + approvals.insert(approval); + + let transaction_v1 = TransactionV1::new(hash.into(), payload, approvals); + let transaction = Transaction::V1(transaction_v1); + println!( + "{}", + hex::encode( + transaction + .to_bytes() + .expect("Expected transaction to correctly serialize") + ) + ); +``` diff --git a/versioned_docs/version-2.0.0/concepts/serialization/transaction-serialization-example.md b/versioned_docs/version-2.0.0/concepts/serialization/transaction-serialization-example.md new file mode 100644 index 000000000..9b9418322 --- /dev/null +++ b/versioned_docs/version-2.0.0/concepts/serialization/transaction-serialization-example.md @@ -0,0 +1,315 @@ +# Transaction serialization example + +``` +**PLEASE NOTE** In this document long snippets representing hex-encoded bytes are split into 64 character lines. Putting such a text in multiple lines does not mean that the newline character is part of the binary payload - newlines are used purely as formatting. +``` + +In this document we will go through byte-serialization of a full Transaction example. We will first describe an example Transaction of variant Version1 and afterwards serialize it's parts to assemble a binary representation of the transaction. + +In this document when we do signing of the hash it has beed done with a secret keys which `der` encoding is: +`0x302e020100300506032b6570042204209090909090909090909090909090909090909090909090909090909090909090` + +## Structure of the example transaction + +- Transaction + + - Transaction of variant Version1 + + - `hash`: 0xde78f579a9afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde2937337 (hex encoded bytes of the Digest) + - `payload`: + + - `initiator_addr`: `PublicKey` case with internal key of `Ed25519` variant and the actual key bytes as: `0x011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9` + - `timestamp`: timestamp with 1752478672515 milliseconds in unix epoch time + - `ttl`: time period of 2 hours. + - `chain_name`: string with value `abc` + - `pricing_mode`: `PricingMode` of case `Fixed` with values: + - `additional_computation_factor`: `2` + - `gas_price_tolerance`: `3` + - `fields`: A [map](./primitives.md#map-clvalue-map). This `fields` instance will have the following key-value mappings: + - key `0`; => binary-serialized [`TransactionArgs`](./types.md#transactionargs-transaction-args) of variant `Named` with the inner RuntimeArgs being a map of "a" => "xyz". When serialized, this transaction args structure is 0x1600000000010000000100000061070000000300000078797a0a. An explanation how it was binary serialized see [`serializing transaction args`](#serializing-transaction-args) + - key `1`; value as binary serialized [`TransactionTarget`](./transaction.md#transactiontarget) of variant `Native`. When serialized, this transaction args structure is 0x0d00000001000000000000000100000000. An explanation how it was binary serialized see [`serializing transaction target`](#serializing-transaction-target) + - key `2`; value as binary serialized [`TransactionEntryPoint`](./transaction.md#transactionentrypoint) of variant `AddBid`. When serialized, this transaction args structure is 0x0f000000010000000000000000000100000003. An explanation how it was binary serialized see [`serializing transaction entry point`](#serializing-transaction-target) + - key `3`; value as binary serialized [`TransactionScheduling`](./transaction.md#transactionentrypoint) of variant `Standard`. When serialized, this transaction args structure is 0x0d00000001000000000000000100000000. An explanation how it was binary serialized see [`serializing transaction scheduling`](#serializing-transaction-scheduling) + + - `approvals`: + - `0`: + - `signer`: 0x011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9 (hex encoded bytes of a public key paired with the secret key mentioned a the start of the document) + - `signature`: 0x01bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 (hex encoded bytes of the signature) + +## Serialization of the example Transaction + +The first byte of the serialized pyalod will be `0x01` (based on [this](./transaction.md#version1), knowing that we are serializing `Version1`). +The next bytes are binary representation of [`TransactionV1`](./transaction.md#transactionv1). Binary representation of the `TransactionV1` from the example is: + +``` +0x030000000000000000000100200000000200150100007b010000de78f579a9 +afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde29373370600000000 +000000000001003600000002003e00000003004600000004004d00000005006a +000000c9000000020000000000000000000100010000002200000000011a3818 +79f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366de +079801000000dd6d000000000003000000616263030000000000000000000100 +0100000002000200000003000000010302040000000000160000000001000000 +0100000061070000000300000078797a0a01000f000000010000000000000000 +00010000000002000f00000001000000000000000000010000000303000f0000 +0001000000000000000000010000000001000000011a381879f8a8dc97361d01 +2e3b472207cc7313ed1a81c918eebfa872b93414d901bcc0ee36a4bb5d8d7b89 +34bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9 +bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 +``` + +You can find the step-by-step explanation [here](#serialization-of-transactionv1) + +The final binary representation of the transaction is: + +``` +0x01030000000000000000000100200000000200150100007b010000de78f579 +a9afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde293733706000000 +00000000000001003600000002003e00000003004600000004004d0000000500 +6a000000c9000000020000000000000000000100010000002200000000011a38 +1879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366 +de079801000000dd6d0000000000030000006162630300000000000000000001 +0001000000020002000000030000000103020400000000001600000000010000 +000100000061070000000300000078797a0a01000f0000000100000000000000 +0000010000000002000f00000001000000000000000000010000000303000f00 +000001000000000000000000010000000001000000011a381879f8a8dc97361d +012e3b472207cc7313ed1a81c918eebfa872b93414d901bcc0ee36a4bb5d8d7b +8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541 +e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 +``` + +## Serialization Of TransactionV1 + +To serialize `TransactionV1` we will use the calltable schema (see [here](./transaction.md#transactionv1)). The exaplanation of the individual bytes are below: + +This particular `TransactionV1` consists of three fields: + +- `hash`: `0xde78f579a9afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde2937337` (32 bytes) +- `payload`: `0x0600000000000000000001003600000002003e00000003004600000004004d00000005006a000000c9000000020000000000000000000100010000002200000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366de079801000000dd6d00000000000300000061626303000000000000000000010001000000020002000000030000000103020400000000001600000000010000000100000061070000000300000078797a0a01000f00000001000000000000000000010000000002000f00000001000000000000000000010000000303000f000000010000000000000000000100000000` +- `approvals` : `0x01000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d901bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000` + + | Calltable segment | Hex-fmt representation | Description | + | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | + | HEADER | 0x03000000 | u32 encoded number of calltable header entries (TransactionV1 has 3 fields) | + | HEADER | 0x0000 | u16 encoded field index of the first field (`hash`) | + | HEADER | 0x00000000 | u32 encoded bytes offset where the `hash` starts in the raw payload | + | HEADER | 0x0100 | u16 encoded field index of the second field (`payload`) | + | HEADER | 0x20000000 | u32 encoded bytes offset where the `payload` starts in the raw payload | + | HEADER | 0x0200 | u16 encoded field index of the third field (`approvals`) | + | HEADER | 0x15010000 | u32 encoded bytes offset where the `approvals` starts in the raw payload | + | PAYLOAD | 0x7b010000 | u32 encoded number of bytes of the raw payload | + | PAYLOAD | 0xde78f579a9afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde2937337 | bytes of `hash` | + | PAYLOAD | 0x0600000000000000000001003600000002003e00000003004600000004004d00000005006a000000c9000000020000000000000000000100010000002200000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366de079801000000dd6d00000000000300000061626303000000000000000000010001000000020002000000030000000103020400000000001600000000010000000100000061070000000300000078797a0a01000f00000001000000000000000000010000000002000f00000001000000000000000000010000000303000f000000010000000000000000000100000000 | bytes of `payload` | + | PAYLOAD | 0x01000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d901bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 | bytes of `approvals` | + +Which concatenates to: + +``` +0x030000000000000000000100200000000200150100007b010000de78f579a9 +afb234cb6ee3ab989a44f44a1544caa991a470dfa0eccde29373370600000000 +000000000001003600000002003e00000003004600000004004d00000005006a +000000c9000000020000000000000000000100010000002200000000011a3818 +79f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366de +079801000000dd6d000000000003000000616263030000000000000000000100 +0100000002000200000003000000010302040000000000160000000001000000 +0100000061070000000300000078797a0a01000f000000010000000000000000 +00010000000002000f00000001000000000000000000010000000303000f0000 +0001000000000000000000010000000001000000011a381879f8a8dc97361d01 +2e3b472207cc7313ed1a81c918eebfa872b93414d901bcc0ee36a4bb5d8d7b89 +34bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9 +bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 +``` + +### Serializing Approvals + +To recap, the approvals structure is as follows: + +- `approvals`: + - `0`: + - `signer`: 0x011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9 (hex encoded bytes of the public key) + - `signature`: 0x01bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 (hex encoded bytes of the signature) + +The binary representation "blob" will be: + +- 0x01000000 - `u32` encoded number of entries (1) +- 0x011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9 - the signer bytes +- 0x01bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f6288490879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b8674c979c8c86000 - the signature bytes + +Concatenated: + +``` +0x01000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebf +a872b93414d901bcc0ee36a4bb5d8d7b8934bbd2e09270456eb201db15f62884 +90879c9a8e44d5a40514600952e6a541e9bf8f0bcc7f9dcec55533c0faec0b86 +74c979c8c86000 +``` + +### Serializing payload + +To serialize `TransactionV1Payload` we will use the calltable schema (see [here](./transaction.md#transactionv1payload)). The exaplanation of the individual bytes are below: + +This particular `TransactionV1Payload` consists of six fields: + +- `initiator_addr`: it's binary serialization is `0x020000000000000000000100010000002200000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9` (see [here](#serializing-initiatoraddr)) +- `timestamp`: it's binary serialization is: `0x8366de0798010000` (see [here](#serializing-timestamp)) +- `ttl`: it's binary serialization is: `0x00dd6d0000000000` (see [here](#serializing-ttl)) +- `chain_name`: it's binary serialization is: `0x03000000616263` , (see [here](./primitives.md#clvalue-string)) +- `pricing_mode`: it's binary serialization is: `0x0300000000000000000001000100000002000200000003000000010302` , (see [here](#serializing-pricing-mode)) +- `fields`: it's binary serialization is: `0x0400000000001600000000010000000100000061070000000300000078797a0a01000f00000001000000000000000000010000000002000f00000001000000000000000000010000000303000f000000010000000000000000000100000000` , (see [here](#serializing-fields)) + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x06000000 | u32 encoded number of calltable header entries (this PricingMode binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (`initiator_addr`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| HEADER | 0x0100 | u16 encoded field index of the second field (`timestamp`) | +| HEADER | 0x36000000 | u32 encoded bytes offset where the `timestamp` starts in the raw payload | +| HEADER | 0x0200 | u16 encoded field index of the second field (`ttl`) | +| HEADER | 0x3e000000 | u32 encoded bytes offset where the `ttl` starts in the raw payload | +| HEADER | 0x0300 | u16 encoded field index of the second field (`chain_name`) | +| HEADER | 0x46000000 | u32 encoded bytes offset where the `chain_name` starts in the raw payload | +| HEADER | 0x0400 | u16 encoded field index of the second field (`pricing_mode`) | +| HEADER | 0x4d000000 | u32 encoded bytes offset where the `pricing_mode` starts in the raw payload | +| HEADER | 0x0500 | u16 encoded field index of the second field (`fields`) | +| HEADER | 0x6a000000 | u32 encoded bytes offset where the `fields` starts in the raw payload | +| PAYLOAD | 0xc9000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD | 0x020000000000000000000100010000002200000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9 | bytes of `initiator_addr` value | +| PAYLOAD | 0x8366de0798010000 | bytes of `timestamp` value | +| PAYLOAD | 0x00dd6d0000000000 | bytes of `ttl` value | +| PAYLOAD | 0x03000000616263 | bytes of `chain_name` value | +| PAYLOAD | 0x0300000000000000000001000100000002000200000003000000010302 | bytes of `pricing_mode` value | +| PAYLOAD | 0x0400000000001600000000010000000100000061070000000300000078797a0a01000f00000001000000000000000000010000000002000f00000001000000000000000000010000000303000f000000010000000000000000000100000000 | bytes of `fields` value | + +Which concatenates to: + +``` + 0x0600000000000000000001003600000002003e00000003004600000004004d00000005006a000000c9000000020000000000000000000100010000002200000000011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d98366de079801000000dd6d00000000000300000061626303000000000000000000010001000000020002000000030000000103020400000000001600000000010000000100000061070000000300000078797a0a01000f00000001000000000000000000010000000002000f00000001000000000000000000010000000303000f000000010000000000000000000100000000 +``` + +#### Serializing Pricing Mode + +To serialize `PricingMode` we will use the calltable schema (see [here](./transaction.md#pricingmode)). This particular PricingMode is of type `Fixed` The exaplanation of the individual bytes are below: + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x03000000 | u32 encoded number of calltable header entries (this PricingMode binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (for PricingMode, this is the `variant discriminator`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| HEADER | 0x0100 | u16 encoded field index of the second field (`additional_computation_factor`) | +| HEADER | 0x01000000 | u32 encoded bytes offset where the `gas_price_tolerance` starts in the raw payload | +| HEADER | 0x0200 | u16 encoded field index of the second field (`gas_price_tolerance`) | +| HEADER | 0x02000000 | u32 encoded bytes offset where the `additional_computation_factor` starts in the raw payload | +| PAYLOAD | 0x03000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD | 0x01 | u8 encoded variant discriminator value for `Fixed` (1) | +| PAYLOAD | 0x03 | u8 encoded value of `gas_price_tolerance` | +| PAYLOAD | 0x02 | u8 encoded value of `additional_computation_factor` | + +Which concatenates to: + +``` + 0x0300000000000000000001000100000002000200000003000000010302 +``` + +#### Serializing payload.fields + +Fields is a [map](./primitives.md#map-clvalue-map) which keys are u16 and values are collections of bytes. We can assemble the binary serialization as follows: + +| hex-encoded bytes | Explanation | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------ | +| 0x04000000 | u32 encoded number of elements in the map (4) | +| 0x0000 | u16 encoded key: `0` | +| 0x1600000000010000000100000061070000000300000078797a0a | binary payload of the first value (see [here](#serializing-transaction-args)) | +| 0x0100 | u16 encoded key: `1` | +| 0x0f000000010000000000000000000100000000 | binary payload of the first value (see [here](#serializing-transaction-target)) | +| 0x0200 | u16 encoded key: `2` | +| 0x0f000000010000000000000000000100000003 | binary payload of the first value (see [here](#serializing-transaction-entry-point)) | +| 0x0300 | u16 encoded key: `2` | +| 0x0f000000010000000000000000000100000000 | binary payload of the first value (see [here](#serializing-transaction-scheduling)) | + +Which concatenates to: + +``` +0x0400000000001600000000010000000100000061070000000300000078797a +0a01000f00000001000000000000000000010000000002000f000000010000 +00000000000000010000000303000f00000001000000000000000000010000 +0000 +``` + +#### Serializing Timestamp + +Value of this field is serialized as explained [here](./types.md#timestamp-timestamp). It's binary serialization is: `0x8366de0798010000` + +#### Serializing Ttl + +Value of this field is serialized as explained [here](./types.md#timediff-timediff). It's binary serialization is: `0x00dd6d0000000000` + +#### Serializing InitiatorAddr + +To serialize `InitiatorAddr` we will use the calltable schema (see [here](./transaction.md#initiatoraddr)). This particular InitiatorAddr is of type `PublicKey` The exaplanation of the individual bytes are below: + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x02000000 | u32 encoded number of calltable header entries (this InitiatorAddr binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (for InitiatorAddr, this is the `variant discriminator`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| HEADER | 0x0100 | index of the second field (for InitiatorAddr, this is the public key) | +| HEADER | 0x01000000 | bytes offset where the field with index `0` starts in the payload | +| PAYLOAD | 0x22000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD | 0x00 | value for the variant discriminator (`0` means "PublicKey") | +| PAYLOAD | 0x011a381879f8a8dc97361d012e3b472207cc7313ed1a81c918eebfa872b93414d9 | raw bytes of the public key | + +And the concatenated version is: + +``` +0x020000000000000000000100010000002200000000011a381879f8a8dc9736 +1d012e3b472207cc7313ed1a81c918eebfa872b93414d9 +``` + +### Serializing Transaction Args + +To recap, the structure of `TransactionArgs` which we want to serialize is `TransactionArgs` of variant `Named`, the inner `RuntimeArgs`being a mapping of `"a" => "xyz"`. +Firstly let's serialize `RuntimeArgs`. It will be a collection of [NamedArg](./types.md#namedarg-namedarg). The collection has one element, so the first 4 bytes will be `0x010000`, followed by the first argumentname ("a") which binary reprentation is `0x0100000061`, followed by cl-value representation of `xyz` string which is `0x070000000300000078797a0a`. This gives binary representation of `RuntimeArgs`: `0x010000000100000061070000000300000078797a0a` By looking at [TransactionArgs doc](./types.md#transactionargs-transaction-args) we see that the binary represenation will be `0x00` followed by serialization of the RuntimeArgs, which gives `0x00010000000100000061070000000300000078797a0a`. We also should notice that the value that we will be putting into the `fields` map is going to be a binary representation of a collection of bytes. We will need to prepend the raw payload with the bytes-length of the payload (as described [here](./types.md#bytes-bytes)). The payload consists of 22 bytes, so the u32 representation of it's length is going to be `0x16000000` So the final "blob" of bytes that we will be putting into the `fields` map will be: `0x1600000000010000000100000061070000000300000078797a0a`. + +### Serializing Transaction Target + +To recap, the TransactionTarget which we want to serialize is a `Native` one. To serialize this we will be using the calltable scheme. To construct the binary representation we will need: + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x01000000 | u32 encoded number of calltable header entries (this TransactionTarget binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (for TransactionTarget, this is the `variant discriminator`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| PAYLOAD | 0x01000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD | 0x00 | first field (variant discriminator) value serialized (`TransactionTarget::Native`) serialized as u8 | + +Which gives a binary representation of: `0x010000000000000000000100000000` +We also should notice that the value that we will be putting into the `fields` map is going to be a binary representation of a collection of bytes. We will need to prepend the raw payload with the bytes-length of the payload (as described [here](./types.md#bytes-bytes)). The payload consists of 15 bytes, so the u32 representation of it's length is going to be `0x0f000000` So the final "blob" of bytes that we will be putting into the `fields` map will be: `0x0f000000010000000000000000000100000000`. + +### Serializing Transaction Entry Point + +To recap, the TransactionEntryPoint which we want to serialize is a `AddBid` one. To serialize this we will be using the calltable scheme. To construct the binary representation we will need: + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x01000000 | u32 encoded number of calltable header entries (this TransactionEntryPoint binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (for TransactionEntryPoint, this is the `variant discriminator`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| PAYLOAD | 0x01000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD | 0x03 | first field (variant discriminator) value serialized (`TransactionEntryPoint::AddBid`) serialized as u8 | + +Which gives a binary representation of: `0x010000000000000000000100000003` +We also should notice that the value that we will be putting into the `fields` map is going to be a binary representation of a collection of bytes. We will need to prepend the raw payload with the bytes-length of the payload (as described [here](./types.md#bytes-bytes)). The payload consists of 15 bytes, so the u32 representation of it's length is going to be `0x0f000000` So the final "blob" of bytes that we will be putting into the `fields` map will be: `0x0f000000010000000000000000000100000003`. + +### Serializing Transaction Scheduling + +To recap, the TransactionScheduling which we want to serialize is a `Standard` one. To serialize this we will be using the calltable scheme. To construct the binary representation we will need: + +| Calltable segment | Hex-fmt representation | Description | +| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| HEADER | 0x01000000 | u32 encoded number of calltable header entries (this TransactionScheduling binary representation will only have one field) | +| HEADER | 0x0000 | index of the first field (for TransactionScheduling, this is the `variant discriminator`) | +| HEADER | 0x00000000 | bytes offset where the field with index `0` starts in the payload (we have no previous fields, so there is no offset) | +| PAYLOAD | 0x01000000 | u32 encoded number of bytes of the raw payload | +| PAYLOAD |  0x00 | raw payload | + +Which gives a binary representation of: `0x010000000000000000000100000000` +We also should notice that the value that we will be putting into the `fields` map is going to be a binary representation of a collection of bytes. We will need to prepend the raw payload with the bytes-length of the payload (as described [here](./types.md#bytes-bytes)). The payload consists of 15 bytes, so the u32 representation of it's length is going to be `0x0f000000` So the final "blob" of bytes that we will be putting into the `fields` map will be: `0x0f000000010000000000000000000100000000`. diff --git a/versioned_docs/version-2.0.0/concepts/serialization/transaction.md b/versioned_docs/version-2.0.0/concepts/serialization/transaction.md index a066be930..5bdf5a803 100644 --- a/versioned_docs/version-2.0.0/concepts/serialization/transaction.md +++ b/versioned_docs/version-2.0.0/concepts/serialization/transaction.md @@ -5,7 +5,7 @@ | [Deploy](#deploy) | | [Version1](#version1) | -A transaction is an enum-type whose variants represent atomic units of work that can be sent to the node for execution. +A transaction is an tagged-union type whose variants represent atomic units of work that can be sent to the node for execution. Currently it consists of two possible variants: @@ -23,7 +23,8 @@ Serializing a `Transaction` of variant `Deploy`: ## Version1 -Transaction::Version1 is the new way that work can be proposed to a node. It's nature is more amorphic than Transaction::Deploy. This type of Transaction uses a self-describing binary serialization scheme (comparing to other [Binary Serialization Standard](./index.md) types). The self-describing scheme is called `Calltable serialization` in this document. An in-depth description of how this self-describing standard works is in the [calltable serialization](./calltable-serialization.md) document. We will be using `serialization_index` and `variant discriminator` terms, their interpretation is explained in the [calltable serialization](./calltable-serialization.md) document also. +Transaction::Version1 is the new way that work can be proposed to a node. It's nature is more amorphic than Transaction::Deploy. This type of Transaction uses a self-describing binary serialization scheme (comparing to other [Binary Serialization Standard](./index.md) types). The self-describing scheme is called `Calltable serialization` in this document. In general, the layout of this new style of transaction is ["tagged-union"](https://en.wikipedia.org/wiki/Tagged_union) oriented. An in-depth description of how this self-describing standard works is in the [calltable serialization](./calltable-serialization.md) document. +In the scope of this documentation, for abbreviation, we will call these "tagged-unions". Tagged unions are data structures that can define very different internal fields depending on which variant is currently being used. For serialization we denote the variant (effectively - "which variant of the union was created for this instance of the union type") and serialize it alongside the fields. This "variant marking" is stored as a one byte unsigned [number](./primitives.md#numeric-clvalue-numeric) and will be referred to in this document as `variant discriminator`. The terms `serialization_index` and `variant discriminator` (which we use in this document) are also explained in the [calltable serialization](./calltable-serialization.md) document also. Serializing a `Transaction` of variant `Version1`: @@ -38,7 +39,7 @@ Serializing a `Transaction` of variant `Version1`: - `payload`- of type [`TransactionV1Payload`](#transactionv1payload), contains all the actual data that the transaction sends to node. It's `serialization_index` is `1` - `approvals` - collection of [Approvals](./structures.md#approval) being signatures over `hash`. It's `serialization_index` is `2` -### TransactionV1Payload +#### TransactionV1Payload `TransactionV1Payload` (serialized using calltable scheme) consists of: @@ -49,7 +50,7 @@ Serializing a `Transaction` of variant `Version1`: - `pricing_mode` - [PricingMode](#pricingmode) declaration of how the transaction should be payed for. It's `serialization_index` is `4` - `fields` - please see [v1.payload.fields](#v1payloadfields) section. It's `serialization_index` is `5` -#### InitiatorAddr +##### InitiatorAddr `InitiatorAddr` (serialized using calltable scheme) consists of: @@ -60,7 +61,7 @@ Serializing a `Transaction` of variant `Version1`: - variant discriminator of value `1` - [`AccountHash`](./types.md#account-hash-account-hash) serialized under serialization key `1` -#### PricingMode +##### PricingMode `PricingMode` (serialized using calltable scheme) consists of: @@ -77,9 +78,9 @@ Serializing a `Transaction` of variant `Version1`: - variant discriminator of value `2` - field `receipt` of type [Digest](./types.md#digest-digest) with serialization index `1` -### V1.payload.fields +#### Version1.payload.fields -This is an amorphous data holder. It is serialized as an [ordered collection](./primitives.md#list-clvalue-list) of [tuples](./primitives.md#tuple-clvalue-tuple) holding (u16, [Bytes](./types.md#bytes-bytes)). By u16 we understand an unsigned 2 byte number (see [numeric](./primitives.md#numeric-clvalue-numeric)). +This is an amorphous data holder. It is serialized as a [map](./primitives.md#map) of key `u16` and value `Byte`. By u16 we understand an unsigned 2 byte number (see [numeric](./primitives.md#numeric-clvalue-numeric)). `Byte` a [collection of bytes](./primitives.md#list-clvalue-list). The invariants for this field are: - keys (first tuple entries) are unique @@ -91,23 +92,12 @@ This field is design in this amorphous way to facilitate the possibility of resh _Currently_ the "keys" (first tuple entries) of the `fields` map are interpreted as: -- payload with key `0`: an instance of [`TransactionArgs`](#transactionargs) +- payload with key `0`: an instance of [`TransactionArgs`](./types.md#transactionargs-transaction-args) - payload with key `1`: an instance of [`TransactionTarget`](#transactiontarget) - payload with key `2`: an instance of [`TransactionEntryPoint`](#transactionentrypoint) - payload with key `3`: an instance of [`TransactionScheduling`](#transactionscheduling) -#### TransactionArgs - -`TransactionArgs` (serialized using calltable scheme) consists of: - -- in variant `Named` - - variant discriminator of value `0` - - [RuntimeArgs](./types.md#runtimeargs-runtimeargs) with serialization index `1` -- in variant `Bytesrepr` - - variant discriminator of value `1` - - [Bytes](./types.md#bytes-bytes) with serialization index `1` - -#### TransactionTarget +##### TransactionTarget `TransactionTarget` (serialized using calltable scheme) consists of: @@ -123,7 +113,7 @@ _Currently_ the "keys" (first tuple entries) of the `fields` map are interpreted - field `module_bytes` of type `Bytes` with serialization index `2` - field `runtime` of type [TransactionRuntimeParams](#transactionruntimeparams) with serialization index `2` -#### TransactionInvocationTarget +##### TransactionInvocationTarget `TransactionInvocationTarget` (serialized using calltable scheme) consists of: @@ -137,12 +127,14 @@ _Currently_ the "keys" (first tuple entries) of the `fields` map are interpreted - variant discriminator of value `2` - field `addr` which is a 32 bytes hash digest with serialization index `1` - field `version` of type `Option` ([option](./primitives.md#option-clvalue-option) of 4 bytes unsigned [number](./primitives.md#numeric-clvalue-numeric)) with serialization index `2` + - field `protocol_version_major` of type `u32` (4 bytes unsigned [number](./primitives.md#numeric-clvalue-numeric)). It's serialization index is `3`. This field is not mandatory - in fact in the reference rust implementation it is defined as `Option`. If it is present it should be serialized as `u32` under index `3`. But if it's not present, there will be no entry for it at all (both in the calltable section of `TransactionInvocationTarget` or payload) - in variant `ByPackageName` - variant discriminator of value `3` - field `name` of type `String` with serialization index `1` - field `version` of type `Option` ([option](./primitives.md#option-clvalue-option) of 4 bytes unsigned [number](./primitives.md#numeric-clvalue-numeric)) with serialization index `2` + - field `protocol_version_major` of type `u32` (4 bytes unsigned [number](./primitives.md#numeric-clvalue-numeric)). It's serialization index is `3`. This field is not mandatory - in fact in the reference rust implementation it is defined as `Option`. If it is present it should be serialized as `u32` under index `3`. But if it's not present, there will be no entry for it at all (both in the calltable section of `TransactionInvocationTarget` or payload) -#### TransactionRuntimeParams +##### TransactionRuntimeParams `TransactionRuntimeParams` (serialized using calltable scheme) consists of: @@ -153,7 +145,7 @@ _Currently_ the "keys" (first tuple entries) of the `fields` map are interpreted - field `transferred_value` of type `u64` (8 bytes unsigned [number](./primitives.md#numeric-clvalue-numeric)) with serialization index `1` - field `seed` of type `Option<[u8; 32]>` ([option](./primitives.md#option-clvalue-option) of 32 bytes [Byte array](./primitives.md#bytearray-clvalue-bytearray)) with serialization index `2` -#### TransactionEntryPoint +##### TransactionEntryPoint `TransactionEntryPoint` (serialized using calltable scheme) consists of: @@ -185,9 +177,17 @@ _Currently_ the "keys" (first tuple entries) of the `fields` map are interpreted - in variant `Burn`: - variant discriminator of value `12` -#### TransactionScheduling +##### TransactionScheduling `TransactionScheduling` (serialized using calltable scheme) consists of: - in variant `Standard`: - variant discriminator of value `0` + +## Serialization example + +Please see [this document](./transaction-serialization-example.md) to see an in-depth step-by-step example of deserializing a transaction + +## Deserialization example + +Please see [this document](./transaction-deserialization-example.md) to see an in-depth step-by-step example of deserializing a transaction diff --git a/versioned_docs/version-2.0.0/concepts/serialization/types.md b/versioned_docs/version-2.0.0/concepts/serialization/types.md index f038c7242..71e65aebd 100644 --- a/versioned_docs/version-2.0.0/concepts/serialization/types.md +++ b/versioned_docs/version-2.0.0/concepts/serialization/types.md @@ -898,3 +898,11 @@ A purse used for unbonding, replaced in 1.5 by [UnbondingPurse](#unbondingpurse) - `amount` The unbonding amount, serialized as a [`U512`](./primitives.md#clvalue-numeric) value. + +## TransactionArgs {#transaction-args} + +Arguments passed to execution of a `Transaction::Version1`, serialized as a `u8` identifying tag followed by additional bytes as follows: + +- `Named`: Serializes as a `u8` tag of 0 followed by [`RuntimeArgs`](#runtimeargs). + +- `Bytesrepr`: Serializes as a `u8` tag of 1 followed by [`bytes`](#bytes). \ No newline at end of file diff --git a/versioned_docs/version-2.0.0/developers/dapps/setup-nctl.md b/versioned_docs/version-2.0.0/developers/dapps/setup-nctl.md index 59c3d4c41..4459161c4 100644 --- a/versioned_docs/version-2.0.0/developers/dapps/setup-nctl.md +++ b/versioned_docs/version-2.0.0/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). diff --git a/versioned_docs/version-2.0.0/operators/becoming-a-validator/unbonding.md b/versioned_docs/version-2.0.0/operators/becoming-a-validator/unbonding.md index 84a51f6fb..f86c0aa4a 100644 --- a/versioned_docs/version-2.0.0/operators/becoming-a-validator/unbonding.md +++ b/versioned_docs/version-2.0.0/operators/becoming-a-validator/unbonding.md @@ -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 use it when they want to override the minimum bid staking amount check to the standard output when they 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** |
Staked: 17,536,609,871,045 motes

Withdraw: 17,536,609,871,045 motes

Remaining Stake: 0 motes | `withdraw-bid`
without
`--min-bid-override` | Client guardrail prevents execution with
"**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** |
Staked: 17,536,609,871,045 motes

Withdraw: 7,536,609,871,045 motes

Remaining Stake: 10,000,000,000,000 motes | `withdraw-bid`
without
`--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** |
Before: 17,536,609,871,045 motes

Withdraw: 17,536,609,871,044 motes | `withdraw-bid`
with
`--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** |
Before: 17,536,609,871,045 motes

Withdraw: 7,536,609,871,044 motes | `withdraw-bid`
with
`--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,56 +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 \ ---secret-key \ ---chain-name \ ---payment-amount \ ---session-path /casper-node/target/wasm32-unknown-unknown/release/withdraw_bid.wasm \ ---session-arg="public_key:public_key=''" \ ---session-arg="amount:u512=''" -``` - -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} Check the auction contract for updates to the bid amounts. diff --git a/versioned_docs/version-2.0.0/operators/maintenance/moving-node.md b/versioned_docs/version-2.0.0/operators/maintenance/moving-node.md index c615d0e17..3c0579ae6 100644 --- a/versioned_docs/version-2.0.0/operators/maintenance/moving-node.md +++ b/versioned_docs/version-2.0.0/operators/maintenance/moving-node.md @@ -6,33 +6,21 @@ title: Move a Node This guide is for active validators who want to move their node to another machine. -:::note +## Setup two nodes running in parallel -Starting with node version 1.5, operators need to move the unit files at the database level. This step allows moving the node with nearly zero rewards loss. +This method limits downtime and enables a smooth transition from the old to the new node. It keeps the node in sync with the tip of the chain. -::: +Existing node should be running and in sync with network. We will call this `old node`. It is using your active `validator key`. +Create a second node (`new node`) on another machine. This should sync with the network as `ttl`. This server needs a new key when started, we will call this `backup key`. -## Swapping Keys with a Hot Backup +Important: You NEVER want to run two nodes using the same validator key. Our swap procedure will always stop a node running validator key first. -This method limits downtime and enables a smooth transition from the old to the new node. It keeps the node in sync with the tip of the chain. +### Preparation of keys on both nodes -1. Once a node is running (`current_node`), create a second node (`backup_node`) on another machine. These two nodes will run in parallel. -2. When the `backup_node` is up to date, stop the `current_node`. -3. Move the unit files at the DB level using `rsync`. This step allows moving the node with nearly zero rewards loss. -4. Stop the `backup_node`. -5. Swap keys on the `backup_node`, now the new validator. -6. Restart the `backup_node`. -7. Swap keys on the `current_node`, now the new backup. -8. Restart the `current_node`. - -### Preparation for swapping - -1. Let both nodes synchronize to the tip of the blockchain. Keep the current validating node running with the original validator keyset. - -2. Prepare to swap keys by following these steps: +Prepare to swap keys by following these steps: - Create the following folder structure on both nodes under the `/etc/casper/validator_keys/` directory. - - Create subdirectories for the `current_node` and `backup_node`. + - Create subdirectories for the `validator` and `backup`. - Copy each node's keyset under the corresponding directories. ```bash @@ -40,57 +28,105 @@ This method limits downtime and enables a smooth transition from the old to the ├── public_key.pem ├── public_key_hex ├── secret_key.pem - ├── current_node + ├── validator │ ├── public_key.pem │ ├── public_key_hex │ └── secret_key.pem - └── backup_node + └── backup | ├── public_key.pem | ├── public_key_hex | └── secret_key.pem ``` +By having both keys available, we can swap back if we have any issues. + This setup allows key swapping by running the `sudo -u casper cp * ../` command, as shown below. -### Swapping the nodes +After creating the keys, check and fix file permissions by running `casper-node-util check_premissions` and use `sudo casper-node-util fix_permissions` if needed. + +### Swapping the keys -1. When the `backup_node` is up to date, stop the `current_node`. +To swap keys, we want the node to be stopped first. -2. On the `backup_node` (the future validator), use `rsync` to move the unit files from the `current_node`, located in `/var/lib/casper/casper-node/[NETWORK_NAME]/unit_files`. +```bash +sudo /etc/casper/node_util.py stop +``` -3. On the `backup_node`, run these commands to stop the node, swap keys, and restart the node: +To enable a node to run as validator, we want to copy keys from `validator` directory. - ```bash - sudo systemctl stop casper-node-launcher - cd /etc/casper/validator_keys/current_node +```bash + cd /etc/casper/validator_keys/validator sudo -u casper cp * ../ - sudo systemctl start casper-node-launcher - ``` +``` -4. On the `current_node`, run these commands to stop the node and swap keys: +To enable a node to run as backup, we want to copy keys from `backup` directory. - ```bash - sudo systemctl stop casper-node-launcher - cd /etc/casper/validator_keys/backup_node +```bash + cd /etc/casper/validator_keys/backup sudo -u casper cp * ../ - ``` +``` + +### Timing of swap for consensus + +With Zug consensus, all needed state is persisted to the DB. This allows full network resume if all validators were stopped and started again. This does not +allow moving consensus state as easy as moving unit_files. We are working on a utility to export this and allow importing on new node. -5. Restart the original validator node (`current_node`), which is now the new backup: +If a node is moved without this data and started too soon, we get a situation where the new node signs blocks previously signed. This causes issues. - ```bash - sudo systemctl start casper-node-launcher - ``` +The best method to swap currently uses the Era boundaries to isolate finality signature sending. -### Understanding rewards impact +This will describe how to manually find the last switch block time. -After swapping, the new validator node shows no round length until an era transition occurs and will lose all rewards from the point of the switch until the end of that era. The validator is not ejected but will receive rewards starting with the next era. +We will use the `get-era-summary` command in the `casper-client` to find the last switch block. Then get the block to find the time. +The commands will be shown separated, in case the give errors. If everything works, the single command at the end will give you the time. -:::tip +```bash +$ casper-client get-era-summary | jq -r .result.era_summary.block_hash +2487f80a5b1aed5bd36e19f1ccad075a277d5159319da14b07c3d3d954d269dc +``` + +We can take the block_hash (2487f80a5b1aed5bd36e19f1ccad075a277d5159319da14b07c3d3d954d269dc) to get that block and timestamp. + +```bash +$ casper-client get-block -b 2487f80a5b1aed5bd36e19f1ccad075a277d5159319da14b07c3d3d954d269dc | jq -r .result.block_with_signatures.block.Version2.header.timestamp +2025-09-03T13:15:58.738Z +``` + +This can be combined into a single command: + +`casper-client get-block -b $(casper-client get-era-summary | jq -r .result.era_summary.block_hash | tr -d '/n') | jq -r .result.block_with_signatures.block.Version +2.header.timestamp` + +Time of the era will be 2 hours after this time. Current time in the same format can be shown with `date -Is`. + +We want to start the change over just before the era transition. + +### Swap operation + +Starting at 5 minutes before era transition. Stop both nodes with: + +`sudo /etc/casper/node_util.py stop` + +We do not want to start again until after the Era transition, but we can prepare. + +On the `old node` we replace the validator key, so if it restarts we do not have two of the same keys running. + +```bash + cd /etc/casper/validator_keys/backup + sudo -u casper cp * ../ +``` + +On the `new node` we setup the validator key. + +```bash + cd /etc/casper/validator_keys/validator + sudo -u casper cp * ../ +``` -You could time the swap right before the era ends to minimize reward losses. +Wait until the era transitions past the switch block. This can be monitored using the appropriate `cspr.live` website for the network. -::: +Start the `new node`: -### Checking file permissions +`sudo /etc/casper/node_util.py start` -After the swap, check and fix file permissions by running the `/etc/casper/node_util.py` utility. +Start the `old node` if you want it as a backup. diff --git a/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md b/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md index dacf212f3..a472ec872 100644 --- a/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md +++ b/versioned_docs/version-2.0.0/operators/setup/basic-node-configuration.md @@ -23,6 +23,8 @@ sudo apt install casper-node-launcher You can also build [from source](https://github.com/casper-network/casper-node-launcher). However, all the setup and pull of casper-node releases will be manual. +`casper-node-util` is a helper script for managing a `casper-node` and installed as a debian package dependency of `casper-node-launcher` + :::note The `casper-sidecar` component is also typically installed alongside the node to provide additional APIs and event streaming. For more information, see the [Sidecar Setup](./casper-sidecar.md) page. diff --git a/versioned_docs/version-2.0.0/operators/setup/hardware.md b/versioned_docs/version-2.0.0/operators/setup/hardware.md index 0904c7d43..c099edc43 100644 --- a/versioned_docs/version-2.0.0/operators/setup/hardware.md +++ b/versioned_docs/version-2.0.0/operators/setup/hardware.md @@ -10,8 +10,11 @@ The following hardware specifications are recommended for the Casper [Mainnet](h - 4 Cores - 32 GB Ram -- 2 TB SSD -- Linux machine running Ubuntu 20.04 +- Storage (SSD) + - 2 TB (Archival Nodes) + - 500 GB (TTL Nodes) +- Linux machine running Ubuntu 22.04, 24.04 or Debian 13 + - Binaries are build on 22.04 and will run on Linux having same or higher Clib version. :::note Notes @@ -20,6 +23,7 @@ The following hardware specifications are recommended for the Casper [Mainnet](h - For non-archival nodes, current disc usage is significantly lower (e.g., ~500 GB is sufficient for at least 1 year). It is safe to start with lower capacity and scale up as needed. +- LMDB is a memory backed database. More RAM than recommended will help read performance after data is cached. ::: ### CPU Requirements {#cpu-requirements} diff --git a/versioned_docs/version-2.0.0/operators/setup/install-node.md b/versioned_docs/version-2.0.0/operators/setup/install-node.md index 66fcc0652..5f5b9f4eb 100644 --- a/versioned_docs/version-2.0.0/operators/setup/install-node.md +++ b/versioned_docs/version-2.0.0/operators/setup/install-node.md @@ -18,28 +18,8 @@ The following ports are used by the node: Of these `35000` is the only port required to be open for your node to function, however, opening `8888` will allow others to know general network health. For more details, see the additional information on [Node Endpoints](./node-endpoints.md). ## Operating System Requirements -The recommended OS version is Ubuntu 20.04. - -### Using Ubuntu 22.04 or 24.04 - -Installing using Ubuntu 22.04 or 24.04 follows the same instructions as 20.04 with one exception: - -If you try to install packages, you will receive: - -``` -casper-client : Depends: libssl1.1 (>= 1.1.0) but it is not installable -``` - -This message is due to the default `openssl` moving to 3.* with Ubuntu 22.04. You need to install OpenSSL 1.* for prior versions of Ubuntu to use the Casper binaries with the following command: - -``` -curl -f -JLO http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb -sudo apt install ./libssl1.1_1.1.1f-1ubuntu2_amd64.deb -``` - -## Required Number of Open Files - -Before beginning, [update the maximum open files limit](./open-files.md) for your system. Specifically, update the node's `/etc/security/limits.conf` file as described [here](./open-files.md#updating-limits-conf), to ensure proper node operation. +The recommended OS version is Ubuntu 22.04, Ubuntu 24.04 or Debian 13. +The current binary build OS is Ubuntu 22.04 and a Debian based system with Clib equal to or newer than the build system will work. ## Required Clean Up @@ -63,10 +43,10 @@ The following commands will set up the Casper repository for packages: ```bash sudo mkdir -m 0755 -p /etc/apt/keyrings/ sudo curl https://repo.casper.network/casper-repo-pubkey.gpg --output /etc/apt/keyrings/casper-repo-pubkey.gpg -echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/casper-repo-pubkey.gpg] https://repo.casper.network/releases focal main" | sudo tee -a /etc/apt/sources.list.d/casper.list +echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/casper-repo-pubkey.gpg] https://repo.casper.network/releases jammy main" | sudo tee -a /etc/apt/sources.list.d/casper.list sudo apt update ``` -We are creating /etc/apt/keyrings if needed, so we don't have the issue with this key being trusted by all APT requests if stored in /etc/apt/trusted.gpg.d. +We are creating `/etc/apt/keyrings` if needed, so we don't have the issue with this key being trusted by all APT requests if stored in `/etc/apt/trusted.gpg.d`. ## Required Tools @@ -85,7 +65,7 @@ It defaults to `bash` but can be changed with the `--shell` argument: --shell The type of shell to generate the completion script for [default: bash] [possible values: zsh, bash, fish, powershell, elvish] -sudo casper-client generate-completion --shell powershell +sudo casper-client generate-completion --shell bash ``` You need to source the new auto completion script or log out and log in again to activate it for the current shell: @@ -95,18 +75,22 @@ source /usr/share/bash-completion/completions/casper-client Now you can use `casper-client` and press the `tab` key to get auto completion for your commands. +## Required Number of Open Files + +Before beginning, [update the maximum open files limit](./open-files.md) for your system. Specifically, update the node's `/etc/security/limits.conf` file as described [here](./open-files.md#updating-limits-conf), to ensure proper node operation. + ## Installing All Protocols On **Mainnet**, run: ```bash -sudo -u casper /etc/casper/node_util.py stage_protocols casper.conf +sudo -u casper casper-node-util stage_protocols casper.conf ``` On **Testnet**, run: ```bash -sudo -u casper /etc/casper/node_util.py stage_protocols casper-test.conf +sudo -u casper casper-node-util stage_protocols casper-test.conf ``` ## Validator Keys @@ -163,44 +147,48 @@ If you are using the node for historical data and want to query back to genesis, sync_handling = genesis ``` +DB archives are made of networks and if you are launching an archival node, requesting these from Casper will make node setup much faster. Historical block syncing is the lowest priority in network operation and take more time as the chain grows. + ## Starting the Node Start the node using the following commands: ```bash -sudo /etc/casper/node_util.py rotate_logs -sudo /etc/casper/node_util.py start -``` +sudo casper_node_util start +``` ### Monitoring the Synchronization Process The following command will display the node synchronization details: ```bash -/etc/casper/node_util.py watch +casper_node_util watch ``` -When you first run the watch command, you may see the message `RPC: Not Ready`. Once the node is synchronized, the status will change to `RPC: Ready` and a similar output: - ```bash -Last Block: 630151 (Era: 4153) -Peer Count: 297 -Uptime: 4days 6h 40m 18s 553ms -Build: 1.4.5-a7f6a648d-casper-mainnet -Key: 0147b4cae09d64ab6acd02dd0868722be9a9bcc355c2fdff7c2c244cbfcd30f158 +Last Block: 5473886 (Era: 19015) +Peer Count: 125 +Uptime: 7days 15h 52m 32s +Build: 2.0.3-4c7068d +Key: 01b08d9184ec9daed7f1d2766674746d6cd8460ca6e0274fa48d01c3ded165da4c Next Upgrade: None -RPC: Ready +Reactor State: KeepUp +Available Block Range - Low: 0 High: 5473886 ● casper-node-launcher.service - Casper Node Launcher - Loaded: loaded (/lib/systemd/system/casper-node-launcher.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2022-03-16 21:08:50 UTC; 4 days ago - Docs: https://docs.casper.network - Main PID: 2934 (casper-node-lau) - Tasks: 12 (limit: 4915) - CGroup: /system.slice/casper-node-launcher.service - ├─ 2934 /usr/bin/casper-node-launcher - └─16842 /var/lib/casper/bin/1_4_5/casper-node validator /etc/casper/1_4_5/config.toml + Loaded: loaded (/usr/lib/systemd/system/casper-node-launcher.service; enabled; preset: enabled) + Active: active (running) since Wed 2025-08-13 20:41:05 UTC; 1 week 0 days ago + Docs: https://docs.casper.network + Main PID: 76968 (casper-node-lau) + Tasks: 8 (limit: 18921) + Memory: 10.2G (peak: 11.0G) + CPU: 1d 17h 2min 43.802s + CGroup: /system.slice/casper-node-launcher.service + ├─76968 /usr/bin/casper-node-launcher + └─76971 /var/lib/casper/bin/2_0_3/casper-node validator /etc/casper/2_0_3/config.toml + +Aug 13 20:41:05 ip-10-0-5-211 systemd[1]: Started casper-node-launcher.service - Casper Node Launcher. ``` The reactor state will be in CatchUp mode until it acquires the full tip state, at which point it will shift to KeepUp mode. If you left `sync_to_genesis` as `true`, it will begin syncing back history at this time. @@ -224,6 +212,7 @@ trie_or_chunk_timeouts 0 ``` If the node is not showing active (running) status, it is either stopped or in the process of restarting. +Indexing of the DB on startup can take some time if the node is archival. ### Monitoring the Running Node diff --git a/versioned_docs/version-2.0.0/operators/setup/joining.md b/versioned_docs/version-2.0.0/operators/setup/joining.md index b3d40106f..bc887b763 100644 --- a/versioned_docs/version-2.0.0/operators/setup/joining.md +++ b/versioned_docs/version-2.0.0/operators/setup/joining.md @@ -14,111 +14,47 @@ Visit the [Hardware Specifications](./hardware.md) section and provision your no Follow the instructions on the [Node Setup](./install-node.md) page. -## Step 3: Building the Required Contracts {#step-3-build-contracts} +## Step 3: Creating and Fund Keys for Bonding {#step-3-create--fund-keys-for-bonding} -Use the commands below to build all the necessary contracts for bonding, retrieving rewards, and unbonding. +See the [Node Setup](./basic-node-configuration.md#create-fund-keys) instructions if you have not generated a validator key. This lives in `/etc/casper/validator_keys`. +This will need funded to allow bonding. -1. Clone the casper-node repository. +## Step 4: Updating the Trusted Hash {#step-5-update-the-trusted-hash} -```bash -git clone https://github.com/casper-network/casper-node -``` +The node's `config.toml` needs to be updated with a recent trusted hash. -2. Install these prerequisites, which are also listed [here](https://github.com/casper-network/casper-node#pre-requisites-for-building). +See the [Trusted Hash for Synchronizing](./basic-node-configuration.md#trusted-hash-for-synchronizing) instructions if you have not set up a trusted hash during node installation. -- [Rust](../../developers/writing-onchain-code/getting-started.md#installing-rust) -- [CMake](https://cgold.readthedocs.io/en/latest/first-step/installation.html) -- `pkg-config` - On Ubuntu, use `sudo apt-get install pkg-config` -- `openssl` - On Ubuntu, use `sudo apt-get install openssl` -- `libssl-dev` - On Ubuntu, use `sudo apt-get install libssl-dev` +## Step 5: Setting sync mode -3. Install the [Rust casper-client](../../developers/prerequisites.md#install-casper-client) and fund the [keys](../setup/basic-node-configuration.md#create-fund-keys) you will use for bonding. +The default mode in config for sync is `ttl`. Available options are listed as comments in the `config.toml`. The only sync modes for an operating node are `nosync`, `ttl`, or `genesis`. -4. Use the following commands to build the contracts in release mode. Make sure you have [installed Rust](../../developers/writing-onchain-code/getting-started.md#installing-rust). +`ttl` syncs the Time To Live data, which is the minimum history needed to operate as a validator. `nosync` would need to wait for the ttl period to get this history until possible to transition into `Validate`. -```bash -cd casper-node -make setup-rs -make build-client-contracts -``` +The sync condition needs to be met before it is possible to transition from `KeepUp` to `Validate`. There are two reasons why `ttl` is recommended for a validator. -These commands will build all the necessary Wasm contracts for operating as a validator: -- `activate_bid.wasm` - Reactivates an ejected validator -- `add_bid.wasm` - Enables bonding for validator stake -- `delegate.wasm` - Delegates stake -- `undelegate.wasm` - Undelegates stake -- `withdraw_bid.wasm` - Enables unbonding for validator stake +### Improved performance of caching -## Step 4: Creating and Fund Keys for Bonding {#step-4-create--fund-keys-for-bonding} +`ttl` sync reduces disk space drastically compared to a `genesis` sync archive mode. This improves performance of LMDB DB as it is memory cached and gives higher probablity of cache hits. -See the [Node Setup](./basic-node-configuration.md#create-fund-keys) instructions if you have not generated and funded your validator keys. +### Dangers of `genesis` sync archival validators -## Step 5: Updating the Trusted Hash {#step-5-update-the-trusted-hash} +A node must sync to the tip of the chain and be in `KeepUp` state before transitioning to `Validate` state. However, prior to this transition, the historical sync operation must complete. -The node's `config.toml` needs to be updated with a recent trusted hash. +With a `ttl` node this is the minimum state required to operate as a validator. Even if a node has been shut down for some time, acquiring this data is generally fast. -See the [Trusted Hash for Synchronizing](./basic-node-configuration.md#trusted-hash-for-synchronizing) instructions if you have not set up a trusted hash during node installation. +If a node is in `genesis` sync mode, the historical state required is all the way back to the highest block previously synced. The node cannot transition to `Validate` mode until the full historical sync is complete. Historical sync is deprioritized, so this can cause a considerable delay in getting back operational as a validator after prolonged downtime. -## Step 6: Starting the Node {#step-6-start-the-node} - -Start the node with the `casper-node-launcher`: - -```bash -sudo systemctl start casper-node-launcher -``` - -The above Debian package installs a casper-node service for systemd. - -For more information, visit [GitHub](https://github.com/casper-network/casper-node/wiki#node-operators). - -## Step 7: Confirming the Node is Synchronized {#step-7-confirm-the-node-is-synchronized} - -While the node is synchronizing, the `/status` endpoint is available. You will be able to compare this to another node's status endpoint `era_id` and `height` to determine if you are caught up. You will not be able to perform any `casper-client` calls to your `7777` RPC port until your node is fully caught up. - -Towards the end of the following output, notice the `era_id` and `height` that you can use to determine if your node has completed synchronizing. - -
-Sample output of the /status endpoint - -```json -{ - "api_version": "1.4.3", - "chainspec_name": "casper-test", - "starting_state_root_hash": "e2218b6bdb8137a178f242e9de24ef5db06af7925e8e4c65fa82d41df38f4576", - "peers": [ - { - "node_id": "tls:0097..b253", - "address": "18.163.249.168:35000" - }, - ... - ... - ... - { - "node_id": "tls:ff95..c014", - "address": "93.186.201.14:35000" - } - ], - "last_added_block_info": { - "hash": "8280de05cb34071f276fbe7c69a07cb325ddd373f685877911238b614bdcc5b1", - "timestamp": "2022-01-04T15:33:08.224Z", - "era_id": 3240, - "height": 430162, - "state_root_hash": "ec4ff5c4d0a9021984b56e2b6de4a57188101c24e09b765c3fee740353690076", - "creator": "01ace6578907bfe6eba3a618e863bbe7274284c88e405e2857be80dd094726a223" - }, - "our_public_signing_key": "01cb41ee07d1827e243588711d45040fe46402bf3901fb550abfd08d1341700270", - "round_length": null, - "next_upgrade": null, - "build_version": "1.4.3-a44bed1fd-casper-mainnet", - "uptime": "25days 1h 48m 22s 47ms" -} -``` -
- -## Step 8: Sending the Bonding Request {#step-7-send-the-bonding-request} +## Step 5: Confirming the Node is Synchronized {#step-5-confirm-the-node-is-synchronized} -You can submit a [bonding request](../becoming-a-validator/bonding.md) to change your synchronized node to a validating node. +The `casper-node-util watch` command gives display of current node status. And example output is given on the [Node Setup](./basic-node-configuration.md#create-fund-keys) page. -The bonding request must be sent after the node has synchronized the protocol state and linear blockchain to avoid being ejected for liveness failures. +The node has a reactor state machine displayed as `Reactor State:` in the `watch` command. This is coming from the `localhost:8888/status` endpoint. + +Full status endpoint output can be seen with: `curl localhost:8888/status | jq`. We are piping to `jq` for clean `json` output. +## Step 6: Sending the Bonding Request {#step-6-send-the-bonding-request} +You can submit a [bonding request](../becoming-a-validator/bonding.md) to change your synchronized node to a validating node. + +The bonding request must be sent after the node has synchronized the protocol state and linear blockchain to avoid being ejected for liveness failures. diff --git a/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md b/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md index fae06b053..db7a55304 100644 --- a/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md +++ b/versioned_docs/version-2.0.0/operators/setup/node-endpoints.md @@ -17,6 +17,9 @@ Node operators can modify a node's configuration options, including the port set The default endpoints for Mainnet and Testnet are open by default and are described below in more detail. If the node connects to a different network, the ports may differ depending on how the network was set up. +## Default IP bonding + +On all defaults given in `config-example.toml` which generates `config.toml` have the bond all interfaces `0.0.0.0` address. If you wish to restrict interfaces, provide the correct IP for these config locations. ## Default Networking Port: 35000 {#35000} @@ -28,17 +31,24 @@ bind_address = '0.0.0.0:35000' If the networking port is closed, the node becomes unreachable, and the node won't be discoverable in the network. If this is a validator, it will face eviction. A read-only node will be considered to be offline. - ## Default JSON-RPC HTTP Server Port: 7777 {#7777} -The configuration options for the JSON-RPC HTTP server are under the `rpc_server` section in the `config.toml` file. The `address` using port 7777 is the listening address for JSON-RPC HTTP server. +The configuration options for the JSON-RPC HTTP server is now in `/etc/casper-sidecar/config.toml`, as the RPC service has moved outside of the node. ```md -address = '0.0.0.0:7777' +ip_address = '0.0.0.0' +port = 7777 ``` -DApps would use this address to [interact with the Casper JSON-RPC API](../../developers/json-rpc/index.md). Users would use this address to [interact with the network using CLI](../../developers/cli/index.md). Validators would use this address to [bond](../becoming-a-validator/bonding.md#example-bonding-transaction) or [unbond](../becoming-a-validator/unbonding.md). If this port is closed, the requests coming to this port will not be served, but the node remains unaffected. +DApps would use this address to [interact with the Casper JSON-RPC API](../../developers/json-rpc/index.md). Users would use this address to [interact with the network using CLI](../../developers/cli/index.md). Validators would use this address to [bond](../becoming-a-validator/bonding.md#example-bonding-transaction) or [unbond](../becoming-a-validator/unbonding.md). If this port is closed or the `casper-sidecar` is not installed, the requests coming to this port will not be served, but the node remains unaffected. + +## Default Binary-RPC HTTP Server Port: 7779 {#7779} +The node RPC moved to the `casper-sidecar` and was replaced with the binary RPC interface. This can be exposed externally if desired for direct calling to node in binary format, which is more efficient than JSON-RPC. However, single RPC calls can involve multiple binary port calls to build up expected data. + +```md +address = '0.0.0.0:7779' +``` ## Default REST HTTP Server Port: 8888 {#8888} @@ -52,6 +62,7 @@ Opening port 8888 is recommended but not required. This port allows the node to One may use this port to [get a trusted hash](./basic-node-configuration.md#trusted-hash-for-synchronizing), [verify successful staging](../maintenance/upgrade.md#verifying-successful-staging) during an upgrade, or to [confirm that the node is synchronized](./joining.md#step-7-confirm-the-node-is-synchronized). +If restricting port 8888, it is requested that access is allowed from `3.21.239.186` for the casper-network-monitor to track overall health of the network. ### Example usage diff --git a/versioned_docs/version-2.0.0/operators/setup/node-events.md b/versioned_docs/version-2.0.0/operators/setup/node-events.md index 87f9a26b8..89d50fdcb 100644 --- a/versioned_docs/version-2.0.0/operators/setup/node-events.md +++ b/versioned_docs/version-2.0.0/operators/setup/node-events.md @@ -30,7 +30,7 @@ curl -sN http://HOST:PORT/events?start_from=ID **Example:** ```bash -curl -sN http://65.21.235.219:9999/events?start_from=29267508 +curl -sN http://localhost:9999/events?start_from=29267508 ``` :::note diff --git a/versioned_docs/version-2.0.0/resources/audit-reports/index.md b/versioned_docs/version-2.0.0/resources/audit-reports/index.md new file mode 100644 index 000000000..d17a349fa --- /dev/null +++ b/versioned_docs/version-2.0.0/resources/audit-reports/index.md @@ -0,0 +1,51 @@ +# Casper Network Security Audit Reports + +Welcome to Casper Network's official security audit documentation. + +Our security audit program encompasses both core network infrastructure and ecosystem projects, ensuring comprehensive coverage across the entire Casper Network landscape. + +## Purpose +This page serves as your central hub for accessing security audit reports across the Casper Network ecosystem, by consolidating and sharing security audit reports to promote transparency and enable the ecosystem to make informed decisions about project security. + +## Report Format + +The standardized audit reports provide comprehensive insights into security assessments: + +**Executive Summary** A high-level overview of key findings, risk assessments, and overall security posture suitable for technical and non-technical stakeholders. + +**Audit Scope and Methodology** Detailed information about what was assessed, testing approaches used, and the audit framework applied to ensure thorough coverage. + +**Findings and Recommendations** Complete documentation of identified vulnerabilities, security improvements, and actionable recommendations categorized by severity level. + +**Remediation Status** Current status of addressed findings, implementation timelines, and verification of fixes where applicable. + +**Auditor Information** Details about the auditing firm, their credentials, expertise areas, and methodology standards to help you assess report credibility. + +## Audit Information + +| Project | Prepared by | Report Date/Last Updated | Remediation Status | Full Report | +|---------|-------------|--------------|---------------------|-------------| +| Bridge Contracts | HALBORN | 07/17/2024 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper---allbridge-fa8c33) | +| Shiboo Token - Simplified | HALBORN | 08/21/2024 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper---shiboo-token---simplified-assessment-70b767) | +| Casper 2.0 - Casper Association | HALBORN | 04/17/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/casper-20-12a8fb) | +| Odra - Liquid Staking | HALBORN | 05/27/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/odra---liquid-staking-231379) | +| MAKE CSPR.name | HALBORN | 07/03/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/make-csprname-7b1108) | +| CEP18 | HALBORN | 07/21/2025 | 100% of all REPORTED Findings have been addressed | [Link](https://www.halborn.com/audits/casper-association/cep18-799d0b) | + +## Important Notice + +Security audit reports represent findings at the specific time of assessment. The dynamic nature of software development means that: + +Projects may have implemented security fixes and updates since the original audit date +New features or modifications may have been introduced that weren't part of the original scope +We recommend verifying the current security status directly with project teams before making integration decisions + +For the most current security information, we encourage you to review the latest available reports and contact project maintainers for recent updates. + +## Continuous Security Improvement + +This documentation represents our ongoing commitment to security excellence. We regularly update our audit repository with new reports and maintain current remediation status information to ensure the community has access to the most accurate and up-to-date security intelligence. + +## Contact + +For questions about submissions or repository access, please open an issue or contact the Casper Network team through our official support channels for detailed discussions about findings or methodologies. \ No newline at end of file diff --git a/versioned_sidebars/version-2.0.0-sidebars.json b/versioned_sidebars/version-2.0.0-sidebars.json index 384c56a5e..79041d81f 100644 --- a/versioned_sidebars/version-2.0.0-sidebars.json +++ b/versioned_sidebars/version-2.0.0-sidebars.json @@ -424,6 +424,18 @@ "resources/advanced/storage-workflow", "resources/advanced/cross-contract" ] + }, + { + "type": "category", + "label": "Security Audit Reports", + "collapsible": true, + "collapsed": true, + "link": { + "type": "doc", + "id": "resources/audit-reports/index" + }, + "items": [ + ] } ], "users": [ @@ -542,6 +554,6 @@ "resources/advanced/storage-workflow", "resources/advanced/cross-contract" ] - } + } ] }