From f4871aecd9d75f9a5a3152c2bbb3d56ab4067c06 Mon Sep 17 00:00:00 2001 From: Gift-Naomi Date: Sat, 20 Jul 2024 14:25:04 +0100 Subject: [PATCH 1/2] doc: guide for extending a deployed contract's Wasm code TTL --- .../build/guides/cli/extend-contract-wasm.mdx | 164 +++++++++++++++--- 1 file changed, 143 insertions(+), 21 deletions(-) diff --git a/docs/build/guides/cli/extend-contract-wasm.mdx b/docs/build/guides/cli/extend-contract-wasm.mdx index dd581b6c9..5ac01f961 100644 --- a/docs/build/guides/cli/extend-contract-wasm.mdx +++ b/docs/build/guides/cli/extend-contract-wasm.mdx @@ -4,32 +4,154 @@ hide_table_of_contents: true description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary. --- -You can use the Stellar CLI to extend the TTL of a contract's Wasm bytecode. This can be done in two forms: if you do or do not have the compiled contract locally. If you do have the compiled binary on your local machine: - -```bash -stellar contract extend \ - --source S... \ - --network testnet \ - --wasm ../relative/path/to/soroban_contract.wasm \ - --ledgers-to-extend 535679 \ - --durability persistent + +# Guide: Extending a Deployed Contract's Wasm Code TTL + +This guide provides a step-by-step approach to extending the Time-to-Live (TTL) of a deployed WebAssembly (Wasm) contract. This includes writing the extension logic, deploying the updated contract, and verifying the changes. + +## Prerequisites + +1. **Development Environment**: + - Install Rust and `wasm-pack` for building Wasm contracts. + - Install necessary blockchain development tools (e.g., Substrate, Polkadot, etc.). + - Set up a local node or have access to a testnet for deploying and testing the contract. + +2. **Tools**: + - `cargo`: Rust's package manager. + - `wasm-pack`: Tool for building and publishing Wasm packages. + - Blockchain-specific CLI tools for deployment and interaction. + +## Step-by-Step Guide + +### 1. Define the Contract Structure + +First, create a new Rust project for your Wasm contract if you don’t have one: + +```sh +cargo new my_contract +cd my_contract +``` + +Add the required dependencies in `Cargo.toml`: + +```toml +[dependencies] +# Add dependencies like ink!, substrate, etc., as required +``` + +### 2. Implement the Contract Logic + +In this section, we'll implement the logic for our contract, including the functionality to extend the TTL. + +#### Code Walkthrough + +Here's an example of how the contract might look: + +```rust +#![cfg_attr(not(feature = "std"), no_std)] + +use ink_lang as ink; + +#[ink::contract] +mod my_contract { + #[ink(storage)] + pub struct MyContract { + ttl: u64, + code: Vec, + owner: AccountId, + } + + impl MyContract { + #[ink(constructor)] + pub fn new(initial_ttl: u64) -> Self { + let caller = Self::env().caller(); + Self { + ttl: initial_ttl, + code: Vec::new(), + owner: caller, + } + } + + #[ink(message)] + pub fn extend_ttl(&mut self, extra_time: u64) -> Result<(), &'static str> { + let caller = self.env().caller(); + if caller != self.owner { + return Err("Only the owner can extend the TTL"); + } + self.ttl += extra_time; + Ok(()) + } + + #[ink(message)] + pub fn get_ttl(&self) -> u64 { + self.ttl + } + + #[ink(message)] + pub fn update_code(&mut self, new_code: Vec) -> Result<(), &'static str> { + let caller = self.env().caller(); + if caller != self.owner { + return Err("Only the owner can update the code"); + } + self.code = new_code; + Ok(()) + } + } +} +``` + +#### Explanation + +1. **Contract Definition**: The `MyContract` struct defines the state of the contract, including `ttl` (Time-to-Live), `code` (Wasm code), and `owner` (the account that deployed the contract). + +2. **Constructor**: The `new` function is the constructor, initializing the contract with an initial TTL and setting the caller as the owner. + +3. **Extend TTL**: The `extend_ttl` function allows the owner to extend the contract's TTL by a specified amount of time. It checks if the caller is the owner before proceeding. + +4. **Get TTL**: The `get_ttl` function returns the current TTL of the contract. + +5. **Update Code**: The `update_code` function allows the owner to update the Wasm code. It checks if the caller is the owner before updating the code. + +### 3. Build the Contract + +Next, build the contract to generate the Wasm binary: + +```sh +cargo +nightly contract build +``` + +### 4. Deploy the Contract + +Deploy the contract to the blockchain. This process depends on the specific blockchain you are using. Here’s a generic example: + +```sh +# Use the CLI tool provided by your blockchain framework +substrate-contract deploy --wasm target/wasm32-unknown-unknown/release/my_contract.wasm --constructor "new" --args ``` -This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times). +### 5. Interact with the Contract + +Use the CLI or UI tools provided by the blockchain to interact with your deployed contract. For instance, you can extend the TTL and update the code: -If you do not have the compiled binary on your local machine, you can still use the CLI to extend the bytecode TTL. You'll need to know the Wasm hash of the installed contract code: +```sh +# Extend the TTL +substrate-contract call --contract --message "extend_ttl" --args -```bash -stellar contract extend \ - --source S... \ - --network testnet \ - --wasm-hash \ - --ledgers-to-extend 535679 \ - --durability persistent +# Update the code +substrate-contract call --contract --message "update_code" --args ``` -:::info +### 6. Verify the Changes + +Verify that the TTL has been extended and the code has been updated correctly by calling the respective getter functions: + +```sh +# Get the current TTL +substrate-contract call --contract --message "get_ttl" +``` + +## Conclusion + +By following this guide, you can extend the TTL of a deployed Wasm contract and update its code. Ensure you thoroughly test the contract on a testnet before deploying it to a mainnet. Adjust the contract logic and deployment steps according to the specific blockchain platform you are using. -You can learn more about finding the correct Wasm hash for a contract instance [here (JavaScript)](../rpc/retrieve-contract-code-js.mdx) and [here (Python)](../rpc/retrieve-contract-code-python.mdx). -::: From bb6f865a10746b2bf91a49aaa05b75913d89f09e Mon Sep 17 00:00:00 2001 From: Gift-Naomi Date: Thu, 25 Jul 2024 11:35:50 +0100 Subject: [PATCH 2/2] docs: a guide for extending deployed contract wasm code TTL --- .../build/guides/cli/extend-contract-wasm.mdx | 157 ------------------ ...tend-deployed contract's Wasm Code TTL.mdx | 118 +++++++++++++ 2 files changed, 118 insertions(+), 157 deletions(-) delete mode 100644 docs/build/guides/cli/extend-contract-wasm.mdx create mode 100644 docs/build/guides/cli/extend-deployed contract's Wasm Code TTL.mdx diff --git a/docs/build/guides/cli/extend-contract-wasm.mdx b/docs/build/guides/cli/extend-contract-wasm.mdx deleted file mode 100644 index 5ac01f961..000000000 --- a/docs/build/guides/cli/extend-contract-wasm.mdx +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Extend a deployed contract's Wasm code TTL -hide_table_of_contents: true -description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary. ---- - - -# Guide: Extending a Deployed Contract's Wasm Code TTL - -This guide provides a step-by-step approach to extending the Time-to-Live (TTL) of a deployed WebAssembly (Wasm) contract. This includes writing the extension logic, deploying the updated contract, and verifying the changes. - -## Prerequisites - -1. **Development Environment**: - - Install Rust and `wasm-pack` for building Wasm contracts. - - Install necessary blockchain development tools (e.g., Substrate, Polkadot, etc.). - - Set up a local node or have access to a testnet for deploying and testing the contract. - -2. **Tools**: - - `cargo`: Rust's package manager. - - `wasm-pack`: Tool for building and publishing Wasm packages. - - Blockchain-specific CLI tools for deployment and interaction. - -## Step-by-Step Guide - -### 1. Define the Contract Structure - -First, create a new Rust project for your Wasm contract if you don’t have one: - -```sh -cargo new my_contract -cd my_contract -``` - -Add the required dependencies in `Cargo.toml`: - -```toml -[dependencies] -# Add dependencies like ink!, substrate, etc., as required -``` - -### 2. Implement the Contract Logic - -In this section, we'll implement the logic for our contract, including the functionality to extend the TTL. - -#### Code Walkthrough - -Here's an example of how the contract might look: - -```rust -#![cfg_attr(not(feature = "std"), no_std)] - -use ink_lang as ink; - -#[ink::contract] -mod my_contract { - #[ink(storage)] - pub struct MyContract { - ttl: u64, - code: Vec, - owner: AccountId, - } - - impl MyContract { - #[ink(constructor)] - pub fn new(initial_ttl: u64) -> Self { - let caller = Self::env().caller(); - Self { - ttl: initial_ttl, - code: Vec::new(), - owner: caller, - } - } - - #[ink(message)] - pub fn extend_ttl(&mut self, extra_time: u64) -> Result<(), &'static str> { - let caller = self.env().caller(); - if caller != self.owner { - return Err("Only the owner can extend the TTL"); - } - self.ttl += extra_time; - Ok(()) - } - - #[ink(message)] - pub fn get_ttl(&self) -> u64 { - self.ttl - } - - #[ink(message)] - pub fn update_code(&mut self, new_code: Vec) -> Result<(), &'static str> { - let caller = self.env().caller(); - if caller != self.owner { - return Err("Only the owner can update the code"); - } - self.code = new_code; - Ok(()) - } - } -} -``` - -#### Explanation - -1. **Contract Definition**: The `MyContract` struct defines the state of the contract, including `ttl` (Time-to-Live), `code` (Wasm code), and `owner` (the account that deployed the contract). - -2. **Constructor**: The `new` function is the constructor, initializing the contract with an initial TTL and setting the caller as the owner. - -3. **Extend TTL**: The `extend_ttl` function allows the owner to extend the contract's TTL by a specified amount of time. It checks if the caller is the owner before proceeding. - -4. **Get TTL**: The `get_ttl` function returns the current TTL of the contract. - -5. **Update Code**: The `update_code` function allows the owner to update the Wasm code. It checks if the caller is the owner before updating the code. - -### 3. Build the Contract - -Next, build the contract to generate the Wasm binary: - -```sh -cargo +nightly contract build -``` - -### 4. Deploy the Contract - -Deploy the contract to the blockchain. This process depends on the specific blockchain you are using. Here’s a generic example: - -```sh -# Use the CLI tool provided by your blockchain framework -substrate-contract deploy --wasm target/wasm32-unknown-unknown/release/my_contract.wasm --constructor "new" --args -``` - -### 5. Interact with the Contract - -Use the CLI or UI tools provided by the blockchain to interact with your deployed contract. For instance, you can extend the TTL and update the code: - -```sh -# Extend the TTL -substrate-contract call --contract --message "extend_ttl" --args - -# Update the code -substrate-contract call --contract --message "update_code" --args -``` - -### 6. Verify the Changes - -Verify that the TTL has been extended and the code has been updated correctly by calling the respective getter functions: - -```sh -# Get the current TTL -substrate-contract call --contract --message "get_ttl" -``` - -## Conclusion - -By following this guide, you can extend the TTL of a deployed Wasm contract and update its code. Ensure you thoroughly test the contract on a testnet before deploying it to a mainnet. Adjust the contract logic and deployment steps according to the specific blockchain platform you are using. - - diff --git a/docs/build/guides/cli/extend-deployed contract's Wasm Code TTL.mdx b/docs/build/guides/cli/extend-deployed contract's Wasm Code TTL.mdx new file mode 100644 index 000000000..04a06628f --- /dev/null +++ b/docs/build/guides/cli/extend-deployed contract's Wasm Code TTL.mdx @@ -0,0 +1,118 @@ + +# Guide: Extending a Deployed Contract's Wasm Code TTL on Stellar + +In this guide, we will walk you through the process of extending the Time-to-Live (TTL) of a deployed WebAssembly (Wasm) contract on the Stellar blockchain using the Stellar CLI. + +## Introduction + +Stellar contracts have a TTL (Time-to-Live) that dictates how long the contract's Wasm bytecode is retained on the network. You can use the Stellar CLI to extend this TTL, either by using the compiled contract locally or by referencing the Wasm hash of the deployed contract. + +## Prerequisites + +- **Stellar CLI**: Ensure you have the Stellar CLI installed and configured. +- **Access to the Stellar Network**: Ensure you have access to either the Stellar testnet or mainnet. + +## Extending TTL with Local Binary + +If you have the compiled Wasm binary on your local machine, you can extend the TTL using the following command: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --wasm ../relative/path/to/soroban_contract.wasm \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +### Explanation + +- `--source`: The source account from which the transaction will be sent. +- `--network`: The network on which the transaction will be executed (`testnet` or `mainnet`). +- `--wasm`: The relative path to the local Wasm binary. +- `--ledgers-to-extend`: The number of ledgers to extend the TTL by (maximum allowable is 535,679). +- `--durability`: Specifies the durability of the extension (`persistent`). + +This command sets the TTL to 535,679 ledgers, approximately 30 days based on an average ledger close time of 5 seconds. + +## Extending TTL without Local Binary + +If you do not have the compiled Wasm binary on your local machine, you can extend the TTL using the Wasm hash of the installed contract: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --wasm-hash \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +### Explanation + +- `--wasm-hash`: The hex-encoded hash of the Wasm bytecode. + +## Finding the Wasm Hash + +To extend the TTL without the local binary, you'll need the Wasm hash of the contract. You can retrieve this using Stellar's RPC interface. Refer to the following documentation to find the Wasm hash: + +- [Retrieve Contract Code using JavaScript](../rpc/retrieve-contract-code-js.mdx) +- [Retrieve Contract Code using Python](../rpc/retrieve-contract-code-python.mdx) + +## Example Contract for Extending TTL + +Here's an example of a simple Soroban contract that includes TTL extension functionality: + +### Contract Code + +```rust +#![cfg_attr(not(feature = "std"), no_std)] + +use soroban_sdk::{contractimpl, contracttype, Env, Symbol, BytesN}; + +pub struct Contract; + +#[contractimpl] +impl Contract { + pub fn extend_ttl(env: Env, extra_time: u64) -> u64 { + // Extend the contract's TTL by the specified amount of time + let current_ttl = env.get_ledger().seq(); + let new_ttl = current_ttl + extra_time; + env.set_contract_data(&Symbol::from("ttl"), &new_ttl); + new_ttl + } + + pub fn get_ttl(env: Env) -> u64 { + // Retrieve the current TTL + env.get_contract_data(&Symbol::from("ttl")).unwrap_or(0) + } +} +``` + +### Explanation + +- **extend_ttl**: This function extends the contract's TTL by the specified amount of time. +- **get_ttl**: This function retrieves the current TTL of the contract. + +## Building and Deploying the Contract + +1. **Build the Contract**: + + ```sh + cargo build --target wasm32-unknown-unknown --release + ``` + +2. **Deploy the Contract**: + + Use Stellar CLI or a Stellar SDK to deploy the contract to the network. + +3. **Interact with the Contract**: + + Use Stellar CLI to call the `extend_ttl` and `get_ttl` functions as needed. + +## Conclusion + +By following this guide, you can extend the TTL of a deployed Wasm contract on the Stellar network using the Stellar CLI. Make sure to test thoroughly on the testnet before deploying changes to the mainnet. + + +