The "Getting Started" section is to help new community members start developing on Secret Network using standard tools for Secret Contract development. The goal is to provide an easy guide to follow with step-by-step instructions. We will also review some of the unique characteristics of contracts on Secret Network, though we will keep things at a very high level.

Topics covered:

• Setting up a development Environment

• Compiling and Deploying a Secret Contract

• Interacting with Contracts on the Secret Network

• Breakdown of a Secret Contract (optional)

Most of the topics covered focus directly on Secret Network but are also relevant to other cosmos-based blockchains.

If you have suggestions, improvements, or corrections, let us know on GitHub!

SCRT Labs and Crates.io

Crates.io serves as a centralized repository for Rust packages, also known as "crates." When building applications or libraries with Rust, developers often need to use external libraries for functionality not provided by the standard library, many of which are included on Crates.io. Below is an example of how to import Secret Labs' crates, such as secret-cosmwasm-std, a fork of the original cosmwasm-storage repository adapted for use in SecretNetwork's Secret Contracts.

[dependencies]
cosmwasm-std = { package = "secret-cosmwasm-std", version = "1.1.10" }
cosmwasm-storage = { package = "secret-cosmwasm-storage", version = "1.1.10" }
secret-toolkit-storage = "0.9.0"
secret-toolkit = { git = "https://github.com/scrtlabs/secret-toolkit", tag = "v0.8.0", default-features = false, features = [
  "storage",
  "viewing-key",
  "crypto",
  "utils",
] }
schemars = { version = "0.8.11" }
serde = { version = "1.0" }
thiserror = { version = "1.0" }
cosmwasm-schema = "1.0.0"

Further Reading: Crates vs Dependencies

You can think of "crates" as individual packages or modules in Rust, while "dependencies" refer to external crates that your project relies on for additional functionality.

When developing a Rust project, you will often have dependencies on other crates. These dependencies can come from crates.io (the default Rust package registry), a Git repository (such as one hosted by Secret Labs!), or a local path on your system. The Rust package manager, Cargo, is responsible for managing these dependencies, ensuring that the correct versions are fetched and built, and handling transitive dependencies (i.e., the dependencies of your dependencies).

• Crates: A crate is a package or a module in Rust containing code and resources, like libraries or applications. Crates are the building blocks of Rust projects and are intended to be easily shared and reused. A crate can be a binary (application) or a library. Each crate has a unique name and a Cargo.toml file containing metadata, such as the crate's name, version, authors, and dependencies.

• Dependencies: Dependencies refer to external crates that your Rust project or library relies on for additional functionality. These external crates are not part of your project's codebase but are required for your project to build and function correctly. Dependencies are declared in the Cargo.toml file of your project under the [dependencies] section.

Secret Contracts are written using the CosmWasm framework. CosmWasm contracts are written in Rust, which is later compiled to WebAssembly (or WASM for short). To write our first Secret Contract, we need to set up a development environment with all of the tools required so that you can upload, instantiate, and execute your smart contracts.

Install Requirements

To follow along with the guide, we will be using git, make, rust, and docker.

sudo apt-get install git make

brew install make

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

curl https://sh.rustup.rs -sSf | sh

Add WASM build target

rustup target add wasm32-unknown-unknown

Install Cargo Generate

Cargo generate is the tool you'll use to create a smart contract project. Learn more about cargo-generate here.

cargo install cargo-generate --features vendored-openssl

Install Docker

Docker is an open platform for developing, shipping, and running applications.

Install SecretCLI

SecretCLI is a command-line tool that lets us interact with the Secret Network blockchain. It is used to send and query data as well as manage user keys and wallets.

wget https://github.com/scrtlabs/SecretNetwork/releases/latest/download/secretcli-Linux
chmod +x secretcli-Linux
sudo mv secretcli-Linux /usr/local/bin/secretcli

mkdir "$home\appdata\local\secretcli"
wget -O "$home/appdata/local/secretcli/secretcli.exe" https://github.com/scrtlabs/SecretNetwork/releases/latest/download/secretcli-Windows
$old_path = [Environment]::GetEnvironmentVariable('path', 'user');
$new_path = $old_path + ';' + "$home\appdata\local\secretcli"
[Environment]::SetEnvironmentVariable('path', $new_path,'User');

secretcli version

mv secretcli-macOS secretcli
chmod 755 secretcli

mv secretcli-macOS secretcli
chmod 755 secretcli

For a more detailed and in-depth guide on SecretCLI installation and usage, check out the documentation here.

Now it's time to learn how to compile and deploy your first smart contract 🎉

What is Secret.js?

In the previous section, we learned how to upload, execute, and query a Secret Network smart contract using SecretCLI and Secret testnet. Now we are going to repeat this process, but we will be uploading, executing, and querying our smart contract on a public testnet using Secret.js.

By the end of this tutorial, you will learn how to:

1. Add the Secret Testnet to your keplr wallet (and fund your wallet with testnet tokens)

2. Optimize and compile your Secret Network smart contract

3. Upload and Instantiate your contract using Secret.js

4. Execute and Query your contract using Secret.js

Let's get started!

Environment Configuration

To follow along with the guide, we will be using npm, git, make, rust, and docker. Follow the Setting Up Your Environment guide here if you need any assistance.

Additionally, you will need to have the Secret Testnet configured with your keplr wallet and also fund it with testnet tokens.

Generate your new counter contract

We will be working with a basic counter contract, which allows users to increment a counter variable by 1 and also reset the counter. If you've never worked with smart contracts written in Rust before that is perfectly fine.

The first thing you need to do is clone the counter contract from the Secret Network github repo. Secret Network developed this counter contract template so that developers have a simple structure to work with when developing new smart contracts, but we're going to use the contract exactly as it is for learning purposes.

Go to the folder in which you want to save your counter smart contract and run:

cargo generate --git https://github.com/SecretFoundation/secret-template.git --name my-counter-contract

Start by opening the my-counter-contract project folder in your text editor. If you navigate to my-counter-contract/src you will seecontract.rs, msg.rs, lib.rs, and state.rs—these are the files that make up our counter smart contract. If you've never worked with a Rust smart contract before, perhaps take some time to familiarize yourself with the code, although in this tutorial we will not be going into detail discussing the contract logic.

1. In your root project folder, ie my-counter-contract, create a new folder. For this tutorial I am choosing to call the folder node.

2. In your my-counter-contract/node folder, create a new javascript file––I chose to name mine upload.js.

3. Run npm init -y to create a package.json file.

4. Add "type" : "module" to your package.json file.

5. Install secret.js and dotenv: npm i secretjs@v1.15.0-beta.1 dotenv

6. Create a .env file in your node folder, and add the variable MNEMONIC along with your wallet address seed phrase, like so:

MNEMONIC=grant rice replace explain federal release fix clever romance raise often wild taxi quarter soccer fiber love must tape steak together observe swap guitar

Congrats! 🎉 You now have your environment configured to develop with secret.js.

Compile the Code

Since we are not making any changes to the contract code, we are going to compile it exactly as it is. To compile the code, run make build-mainnet-reproducible in your terminal. This will take our Rust code and build a Web Assembly file that we can deploy to Secret Network. Basically, it just takes the smart contract that we've written and translates the code into a language that the blockchain can understand.

make build-mainnet-reproducible

$env:RUSTFLAGS='-C link-arg=-s'
cargo build --release --target wasm32-unknown-unknown
cp ./target/wasm32-unknown-unknown/release/*.wasm ./contract.wasm

This will create a contract.wasm.gz file in the root directory.

Uploading the Contract

Now that we have a working contract and an optimized wasm file, we can upload it to the blockchain and see it in action. This is called storing the contract code. We are using a public testnet environment, but the same commands apply no matter which network you want to use - local, public testnet, or mainnet.

Start by configuring your upload.js file like so:

import { SecretNetworkClient, Wallet } from "secretjs";
import * as fs from "fs";
import dotenv from "dotenv";
dotenv.config();

const wallet = new Wallet(process.env.MNEMONIC);

const contract_wasm = fs.readFileSync("../contract.wasm.gz");

You now have secret.js imported, a wallet variable that points to your wallet address, and a contract_wasm variable that points to the smart contract wasm file that we are going to upload to the testnet. The next step is to configure your Secret Network Client, which is used to broadcast transactions, send queries and receive chain information.

Secret Network Client

Note the chainId and the url that we are using. This chainId and url are for the Secret Network testnet. If you want to upload to LocalSecret or Mainnet instead, all you would need to do is swap out the chainId and url. A list of alternate API endpoints can be found here.

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://api.pulsar.scrttestnet.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

Now console.log(secretjs) and run node upload.js in the terminal of your my-counter-contract/node folder to see that you have successfully connected to the Secret Network Client:

Uploading with secret.js

To upload a compiled contract to Secret Network, you can use the following code:

let upload_contract = async () => {
  let tx = await secretjs.tx.compute.storeCode(
    {
      sender: wallet.address,
      wasm_byte_code: contract_wasm,
      source: "",
      builder: "",
    },
    {
      gasLimit: 4_000_000,
    }
  );

  const codeId = Number(
    tx.arrayLog.find((log) => log.type === "message" && log.key === "code_id")
      .value
  );

  console.log("codeId: ", codeId);

  const contractCodeHash = (
    await secretjs.query.compute.codeHashByCodeId({ code_id: codeId })
  ).code_hash;
  console.log(`Contract hash: ${contractCodeHash}`);
  
};

upload_contract();

Run node upload.js in your terminal to call the upload_contract() function. Upon successful upload, a codeId and a contractCodeHash will be logged in your terminal:

codeId:  19904
Contract hash: d350eb20b4bf93ce2a060168a1fe6faf58dafa84989bc22d3e83ac665f8c119f

Instantiating the Contract

In the previous step, we stored the contract code on the blockchain. To actually use it, we need to instantiate a new instance of it. Comment out upload_contract() and then add instantiate_contract().

Note that there is an initMsg which contains count:0. You can make the starting count whatever you'd like (as well as the contract label).

let instantiate_contract = async () => {
  // Create an instance of the Counter contract, providing a starting count
  const initMsg = { count: 0 };
  let tx = await secretjs.tx.compute.instantiateContract(
    {
      code_id: codeId,
      sender: wallet.address,
      code_hash: contractCodeHash,
      init_msg: initMsg,
      label: "My Counter" + Math.ceil(Math.random() * 10000),
    },
    {
      gasLimit: 400_000,
    }
  );

  //Find the contract_address in the logs
  const contractAddress = tx.arrayLog.find(
    (log) => log.type === "message" && log.key === "contract_address"
  ).value;

  console.log(contractAddress);
};

instantiate_contract();

Run node upload.js in your terminal to call the instantiate_contract() function. Upon successful instantiation, a contractAddress will be logged in your terminal:

secret1ez0nchvy6awpnnmzqqzvmqz62dcgke80pzaqc7

Congrats 🎉! You just finished uploading and instantiating your first contract on a public Secret Network testnet! Now it's time to see it in action!

Executing and Querying the contract

The way you interact with contracts on a blockchain is by sending contract messages. A message contains the JSON description of a specific action that should be taken on behalf of the sender, and in most Rust smart contracts they are defined in the msg.rs file.

In our msg.rs file, there are two enums: ExecuteMsg, and QueryMsg. They are enums because each variant of them represents a different message which can be sent. For example, the ExecuteMsg::Increment corresponds to the try_increment message in our contract.rs file.

In the previous section, we compiled, uploaded and instantiated our counter smart contract. Now we are going to query the contract and also execute messages to update the contract state. Let's start by querying the counter contract we instantiated.

Query Message

A Query Message is used to request information from a contract; unlike execute messages, query messages do not change contract state, and are used just like database queries. You can think of queries as questions you can ask a smart contract.

Let's query our counter smart contract to return the current count. It should be 0, because that was the count we instantiated in the previous section. We query the count by calling the Query Message get_count {}, which is defined in our msg.rs file. Comment out instantiate_contract() and then add try_query_count().

let try_query_count = async () => {
  const my_query = await secretjs.query.compute.queryContract({
    contract_address: contractAddress,
    code_hash: contractCodeHash,
    query: { get_count: {} },
  });

  console.log(my_query);
};

try_query_count();

The query returns:

{"count": "0"}

Great! Now that we have queried the contract's starting count, let's execute an increment{} message to modify the contract state.

Execute Message

An Execute Message is used for handling messages which modify contract state. They are used to perform contract actions.

The counter contract consists of two execute messages: increment{}, which increments the count by 1, and reset{}, which resets the count to any i32 you want. The current count is 0, let's call the Execute Message increment{} to increase the contract count by 1.

let try_increment_count = async () => {
  let tx = await secretjs.tx.compute.executeContract(
    {
      sender: wallet.address,
      contract_address: contractAddress,
      code_hash: contractCodeHash, // optional but way faster
      msg: {
        increment: {},
      },
      sentFunds: [], // optional
    },
    {
      gasLimit: 100_000,
    }
  );
  console.log("incrementing...");
};

 try_increment_count();

Nice work! Now we can query the contract once again to see if the contract state was successfully incremented by 1. The query returns:

{"count": "1"}

Way to go! You have now successfully interacted with a Secret Network smart contract on the public testnet!

Next Steps

Congratulations! You completed the tutorial and successfully compiled, uploaded, deployed and executed a Secret Contract! The contract is the business logic that powers a blockchain application, but a full application contains other components as well. If you want to learn more about Secret Contracts, or explore what you just did more in depth, feel free to explore these awesome resources:

• Millionaire's problem breakdown - explains how a Secret Contract works

• CosmWasm Documentation - everything you want to know about CosmWasm

• Secret.JS - Building a web UI for a Secret Contract

Contract Messages

The way you interact with contracts on a blockchain is by sending contract messages. A message contains the JSON description of a specific action that should be taken on behalf of the sender, and in most Rust smart contracts they are defined in the msg.rs file.

In our msg.rs file, there are two enums: ExecuteMsg, and QueryMsg. They are enums because each variant of them represents a different message which can be sent. For example, the ExecuteMsg::Increment corresponds to the try_increment message in our contract.rs file.

In the previous section, we compiled, uploaded and instantiated our counter smart contract. Now we are going to query the contract and also execute messages to update the contract state. Let's start by querying the counter contract we instantiated.

Query Message

A Query Message is used to request information from a contract; unlike execute messages, query messages do not change contract state, and are used just like database queries. You can think of queries as questions you can ask a smart contract.

Let's query our counter smart contract to return the current count. It should be 1, because that was the count we instantiated in the previous section. We query the count by calling the Query Message get_count {}, which is defined in our msg.rs file.

secretcli query compute query <your-contract-address> '{"get_count": {}}' --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net 

The query returns:

{"count": "1"}

Great! Now that we have queried the contract's starting count, let's execute an increment{} message to modify the contract state.

Execute Message

An Execute Message is used for handling messages which modify contract state. They are used to perform actual actions.

The counter contract consists of two execute messages: increment{}, which increments the count by 1, and reset{}, which resets the count to any i32 you want. The current count is 1, let's call the Execute Message increment{} to increase the contract count by 1:

secretcli tx compute execute <your-contract-address> '{"increment": {}}' --from <your-wallet> --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net --fees=70000uscrt

SecretCLI will ask you to confirm the transaction before signing and broadcasting. Upon successful confirmation of the transaction, the terminal will return a transaction hash representing your transaction:

Nice work! Now we can query the contract once again to see if the contract state was successfully incremented by 1:

secretcli query compute query <your-contract-address> '{"get_count": {}}' --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net 

The query returns:

{"count": "2"}

Now, we will call one final execute message, reset{}. This will reset the count to an i32 that we specify. I am going to reset the count to 0 by running the following code in SecretCLI:

 secretcli tx compute execute <your-contract-address> '{"reset": {"count": 0}}' --from <your-wallet> --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net --fees=70000uscrt

The query returns:

{"count": "0"}

Way to go! You have now successfully interacted with a Secret Network smart contract using SecretCLI.

Next Steps

Congratulations! You completed the tutorial and successfully compiled, uploaded, deployed and executed a Secret Contract! The contract is the business logic that powers a blockchain application, but a full application contains other components as well. If you want to learn more about Secret Contracts, or explore what you just did more in depth, feel free to explore these awesome resources:

• Millionaire's problem breakdown - explains how a Secret Contract works

• CosmWasm Documentation - everything you want to know about CosmWasm

• Secret.JS - Building a web UI for a Secret Contract

Now that you've set up your development environment, we are going to learn how to compile, upload, and instantiate a smart contract using SecretCLI in your testnet environment.

We will be working with a basic counter contract, which allows users to increment a counter variable by 1 and also reset the counter. If you've never worked with smart contracts written in Rust before that is perfectly fine. By the end of this tutorial you will know how to upload and instantiate a Secret Network smart contract in your terminal using SecretCLI.

Generate your new counter contract

The first thing we need to do is clone the counter contract from the Secret Network github repo. Secret Network developed this counter contract template so that developers have a simple structure to work with when developing new smart contracts, but we're going to use the contract exactly as it is for learning purposes.

Go to the folder in which you want to save your counter smart contract and run:

cargo generate --git https://github.com/SecretFoundation/secret-template.git --name my-counter-contract

Start by opening the my-counter-contract project folder in your text editor. If you navigate to my-counter-contract/src you will seecontract.rs, msg.rs, lib.rs, and state.rs—these are the files that make up our counter smart contract. If you've never worked with a Rust smart contract before, perhaps take some time to familiarize yourself with the code, although in this tutorial we will not be going into detail discussing the contract logic.

Compile the Code

Since we are not making any changes to the contract code, we are going to compile it exactly as it is. To compile the code, run make build-mainnet-reproducible in your terminal. This will take our Rust code and build a Web Assembly file that we can deploy to Secret Network. Basically, it just takes the smart contract that we've written and translates the code into a language that the blockchain can understand.

make build-mainnet-reproducible

$env:RUSTFLAGS='-C link-arg=-s'
cargo build --release --target wasm32-unknown-unknown
cp ./target/wasm32-unknown-unknown/release/*.wasm ./contract.wasm

This will create a contract.wasm.gz file in the root directory.

Storing the Contract

Now that we have a working contract and an optimized wasm file, we can upload it to the blockchain and see it in action. This is called storing the contract code. We are using a testnet environment, but the same commands apply no matter which network you want to use - local, public testnet, or mainnet.

In order to store the contract code, we first must create a wallet address in order to pay for transactions such as uploading and executing the contract.

Creating a Wallet

To interact with the blockchain, we first need to initialize a wallet. From the terminal run:

secretcli keys add myWallet

You should now have access to a wallet with a unique name, address, and mnemonic, which you can use to upload the contract to the blockchain:

The wallet currently has zero funds, which you query by running this secretcli command (be sure to use your wallet address in place of mine)

secretcli query bank balances "secret158v062sat459ygam4y5j9z6p6e6g8wcdw6z4xp"

To fund the wallet so that it can execute transactions, you can get testnet tokens from the faucet here.

Upload the contract

Finally, we can upload our contract:

 secretcli tx compute store contract.wasm.gz --gas 5000000 --from myWallet --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net --fees=70000uscrt

To verify whether storing the code has been successful, we can use SecretCLI to query the chain:

secretcli query compute list-code --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net

Which should give an output similar to the following:

[
   {"code_id":"12163","creator":"secret158v062sat459ygam4y5j9z6p6e6g8wcdw6z4xp","code_hash":"672ff09984b417665122ec5b78dfd045292150c3252e45826f117af29a8aa83e","source":"","builder":""}]}
]

Instantiating the Contract

In the previous step we stored the contract code on the blockchain. To actually use it, we need to instantiate a new instance of it.

secretcli tx compute instantiate <your-code-id> '{"count": 1}' --from <name> --label <your-label> --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net --fees=70000uscrt -y

Let's check that the instantiate command worked:

secretcli query compute list-contract-by-code <your-code-id> --chain-id pulsar-3 --node https://rpc.testnet.secretsaturn.net 

Now we will see the address of our deployed contract

[
    {
        "contract_address": "secret18vd8fpwxzck93qlwghaj6arh4p7c5n8978vsyg",
        "code_id": 1,
        "creator": "secret16u7w28vp68qmldffuc89am4f02045zlfsjht90",
        "label": "counterContract"
    }
]

Congratulations! You just finished compiling and deploying your first contract! Now it's time to see it in action!

Millionaire Problem Decentralized Application

Yao's Millionaires' problem is a secure multi-party computation problem introduced in 1982 by computer scientist and computational theorist Andrew Yao. The problem discusses two millionaires, Alice and Bob, who are interested in knowing which of them is richer without revealing their actual wealth.

we will be working with demonstrates an example implementation that allows two millionaires to submit their net worth and determine who is richer, without revealing their actual net worth.

for the full stack application, on Secret testnet.

In this demo you will learn how to integrate the Secret Millionaire contract with a front end designed in React using Secret.Js. Let's get started!

Frontend library overview

Excluding the instantiation message, the Secret Millionaire smart contract is capable of executing three messages:

1. Submit net worth

2. Reset net worth

3. Query net worth

Thus, we need to design our frontend in an intuitive manner that will allow the user to execute these messages. By the end of this tutorial you will learn how to do the following:

1. Integrate Keplr wallet with React.js

2. Use secret.js to execute multiple transactions simultaneously (submit and reset net worth)

3. Use secret.js to query the updated Secret Millionaire smart contract

Integrating Keplr Wallet with Secret.js

Connect Wallet function

In fewer than 100 lines of code, you have the functionality to connect and disconnect a Keplr wallet and can now use this data in every other part of any dApp you choose to create.

Now that a user can connect to our front end, let's write some functions with Secret.js that execute the submit_net_worth() and reset_net_worth() functions.

Writing the Execution Messages

This function takes in two objects, each representing a millionaire, and sends their name and net worth to the Millionaire smart contract using the broadcast method of the secretjs library. This method accepts an array of transactions to send to the blockchain and an options object. In this case, the options object specifies a gas limit of 300,000, which is the maximum amount of computational work the transactions are allowed to perform before they are halted. Now let's use React.js to fire this function every time a user clicks on a button.

Creating onClick events for Secret.js transactions

The handleSubmit function is a handler for a form submit event in our React application. This function takes user inputs (names and net worths of two millionaires), submits this data to the blockchain, queries the richer millionaire, and updates the UI accordingly:

1. e.preventDefault();: This line stops the default form submission event in a web page (which would typically reload the page).

2. setMillionaire1({ name: name1, networth: networth1 }); and setMillionaire2({ name: name2, networth: networth2 });: These two lines update the states of Millionaire1 and Millionaire2 respectively. setMillionaire1 and setMillionaire2 are state-setting functions from the useState React hook.

3. await submit_net_worth({ name: name1, networth: networth1 }, { name: name2, networth: networth2 });: This line calls the submit_net_worth function described above, passing two objects containing the names and net worths of two millionaires. It then waits for the function to finish.

4. await query_net_worth(myQuery);: This line calls the query_net_worth function and waits for the function to finish.

5. setRicherModalOpen(true); and setShowRicherButton(false);: These two lines update the states controlling whether a modal and a button are displayed in the UI. They hide a button and show a modal that presents the result of the query_net_worth function.

6. alert("Please approve the transaction in keplr.");: If any error is thrown during the execution of the function, it is caught, and an alert is shown to the user instructing them to approve the transaction in Keplr.

Resetting the smart contract state

resetSubmit resets the smart contract state back to 0:

Writing the Query Message

Lastly, we need to be able to query the result of submitted transaction, namely, which millionaire is richer. This function queries the Millionaire contract to get information about who is richer among the previously submitted millionaires, stores the result in the myQuery array, and then we can display information stored in myQuery in our front end.

1. First, we use the queryContract method of the compute module from secretjs library to send a query to the Millionaire contract. This method takes an object as its argument with the following properties:

   • contract_address: The address of the smart contract to which the query is being sent.

   • query: The query message to be sent to the contract. In this case, it's calling the who_is_richer method of the contract, which returns information about the richer of the two millionaires.

   • code_hash: The code hash of the contract to ensure that the contract code hasn't been tampered with.

2. The result of this query is stored in the query variable.

3. The result of the query is then pushed onto the myQuery array. This array stores the results of all queries made so far, and we can display this on our React front end.

Putting it all together