A simple way to describe a blockchain is that it’s a distributed ledger on a peer-to-peer (P2P) network where each node of that network contains a copy of the blockchain state. The state of the blockchain is updated by an application and broadcast to each node, agreeing on this new state through consensus.

Want to learn about Cosmos and the Secret Techstack via a video instead? Check this video series on the Secret Network Youtube.

Horizontal Scaling - Application Specific Blockchains

Cosmos is an ecosystem of independent, interconnected and application specific blockchains commonly referred to as the internet of blockchains. By having all these application specific interconnected blockchains, the ecosystem can easily scale horizontally which avoids most of the bottlenecks and scalability issues we know today on other heterogenous blockchains.

The conceptual layers of a blockchain are:

We will cover in this article the following three layers for an ease of understanding:

• Network layer: Responsible for the propagation of transactions between the nodes of the ecosystem

• Consensus layer: Enables the nodes to agree on the current state of the system.

• Application layer: Responsible for updating the state given a set of transactions, i.e. processing transactions

Tendermint and Cosmos SDK

To reach adoption and grow the internet of blockchain, developers should focus on their application specific development. They should not spend time on building from scratch the consensus and networking layers. That’s what Tendermint core is taking care of by providing Networking and Consensus layers saving a lot of time and headaches for the developers.

The following figure shows the Networking and Consensus layers as “Tendermint Core” and Cosmos SDK as the “Application layer”:

On top of Tendermint Core, Cosmos introduced the Cosmos SDK, an open-source framework for building application specific blockchains with composable modules (plugins) to help developers build their blockchain faster and easier. Developers could build their application directly on Tendermint core using ABCI to interact with Tendermint but Cosmos SDK allows a faster and battle tested path to bootstrap an application.

Interoperability at the Base Layer

In order to scale horizontally and fulfill the vision of an internet of interoperable blockchains, blockchains can support the Inter-Blockchain Communication Protocol (IBC), which enables value transfers, token transfers, and other communication between chains, all without the need to involve exchanges or make compromises regarding the chains' sovereignties. Following figures show blockchains interconnected with IBC (IBC Networks)\

Secret Network is built with the Cosmos SDK and the Tendermint consensus engine. Secret Network provides a platform for scalable, private permissionless smart contracts which can connect to the interchain.

Secret Network leverages novel key management techniques, encryption schemes, and Trusted Execution Environment (TEE) technology to bring encrypted input, output, and state to the blockchain.

The decentralized network of computers that host Secret Network come to a consensus (delegated Proof-of-Stake — Byzantine Fault Tolerance) without ever obtaining access to the data they process. Users can use “viewing keys” to view their sensitive data or enable third parties to do the same.

Secret brings privacy to the Interchain by leveraging CosmWasm IBC compatible smart contracts and IBC native token bridging. In this Section we dive into all of these elements of the techstack.

• Steps Of A Private Transactions - overview

For a video introduction to the Secret techstack you can watch this playlist:

Blockchain technology is a complex base layer allowing open-source protocols and decentralized applications to be built on top of it. Secret is a sovereign layer 1 of the Cosmos ecosystem built with the Cosmos SDK.

This section will walk you through the Secret technology stack to get a better understanding of what’s under the hood of the privacy hub for Web3. This "Blockchain technology" section starts with a quick grasp of the different blockchain layers are and an explanation of the Cosmos stack

In this section we will explain in depth the components of the blockchain stack:

The Cosmos part of the Secret Techstack is also covered Part 1 and Part 2 of the Secret Network techstack video series.

Secret Network unlocks possibility by offering scalable permissionless smart contracts with a private by default design— bringing novel use cases to blockchain not feasible on public systems. Secret Network was the first protocol to provide private smart contracts on mainnet, live since September 2020.

Secret Network is built with the Cosmos Software Development Kit (SDK) bringing interoperable privacy to the entire Cosmos and EVM ecosystems. Secret Network uses a combination of the Intel SGX (Software Guard Extension) Trusted Execution Environment technology, several encryption schemes, and key management to bring privacy by default to blockchain users. Secret Contracts are an implementation of the Rust-based smart contract compiling toolkit CosmWasm, adding private metadata possibilities. Secret Network is powered by the Native public coin SCRT which is used for fees, Proof-of-Stake, security, and Governance. With more than 30+ Dapps on mainnet and 100+ full time builders, Secret Network aims to bring privacy to the world.

Join the community

We host a weekly community developer call on Mondays at 5pm UTC on Discord. You can ask questions, get help with your project, get updates from the Secret team, and meet fellow Secret developers.

• Discord

• Telegram

• Twitter

• Forum

• Blog

• Homepage

Get the latest version: https://github.com/scrtlabs/SecretNetwork

Interconnected Blockchains

The core vision of Cosmos is to scale horizontally by having an ecosystem of interconnected application specific blockchains. Inter-Blockchain Communication Protocol (IBC) is responsible for interconnecting heterogeneous blockchains or in another way, relaying data packets between arbitrary state machines (i.e application blockchains).

It could also be defined as a generic and standard protocol implementation for transferring value between chains, not only limited to Cosmos chains as other blockchains with different consensus could support IBC to communicate with the Cosmos Ecosystem (Polkadot, Ethereum through a peg zone for example).

IBC provides a common protocol for blockchains to communicate in a standardized and trustless way.

There is a lot to talk about IBC in terms of current and future capabilities, and the technology layers, but that’s not the goal of this paragraph. We’ll go through the high level principles here.

The IBC stack

IBC is composed of two layers:

• Transport layer (IBC/TAO) - provides the infrastructure for establishing secure connections and data packets authentication between chains

• Application layer (IBC/APP) - defines how data packets should be packaged and interpreted by sending and receiving chains

This is wrapped up in a “light client” and relayers are external components for passing messages through blockchains:

Relayers

Relayers are off-chain actors ensuring the “physical” connection between two chains, scanning the state of the two interconnected chains, looking for an intention to send a transaction on a chain and then relaying the data and its commitment proof to the other chain.

For example in the case of fungible token transfer between two chains, the relayers are responsible for proving that your tokens are locked in Chain A and giving a representation (Voucher) on Chain B.

Relayers are using the light client of each blockchain to verify incoming messages on chain A and submit them (and the proof of commitment) on chain B. Chain A can’t send data directly to chain B and instead “commit” the hash of the data packet in its own state machine. That’s this specific state that relayers are monitoring to send this packet and its proof to the chain B.

Native security - no additional trust

The major difference of IBC compared to existing bridge solutions is that there are no third parties to trust, no multisig involved, for transferring value/messages between blockchains. This concept of IBC native security means that if you trust chain A and chain B then you also trust IBC-TokenA on chain B and vice versa. As long as relayers are operated by any party and channels/ports are open and authentication successful between blockchains, messages can be passed along.

An analogy of IBC could be seen as an internet application on a computer. A channel is an IP connection, with the IBC portID being an IP port and the IBC channelID being an IP address.

IBC security does not depend on third parties to verify the validity of transactions between blockchain. IBC security is mostly done by the light clients who verify proofs of commitments and the state of the two interconnected blockchain. In short terms, IBC security is based on::

• Trust in the chains you connect with

• Fault isolation mechanisms, to limit damage done if a chain is acting maliciously

IBC is then still Byzantine resistant thanks to the proof validation by the light client. If a relayer were to act maliciously, the packet would be rejected by the counterparty chain because the proof would be invalid (because light client and relayers are independent).

Interoperable messaging & contracts

Fungible token transfer is one example but IBC allows for Non-Fungible token transfer, multi-chain smart contracts and interchain accounts (interacting on a blockchain account from another source blockchain). This is the function enabling Secret Network to be the privacy hub for the Interchain. Other Cosmos chains can store and manipulate private data (even private keys) on Secret Network from the comfort of their own chain, Privacy as a service.

Finally, below a figure explaining the travel of an IBC packet between blockchains:

CosmWasm is a modular framework for writing secure smart contracts in Rust, and using them in any blockchain built with the Cosmos SDK. It's a low-level tool developers use to implement entirely new features. The framework enables the creation of modular and reusable code for smart contracts, without being exposed to the underlying nature of the blockchain and its inner workings. These smart contracts are run securely inside a WebAssembly (WASM) virtual machine (VM). WASM acts as an intermediate language compiler for the VM.

CosmWasm Smart Contracts

Everything in blockchain is a smart contract. To understand what this means, it helps to know that a smart contract is simply a set of rules that describe how parties interact with each other. These rules are written as code and stored on the blockchain, where they can be executed by the network itself.

The blockchain world has seen several attempts to make smart contracts safer, but these solutions were either too complicated or simply didn't work. CosmWasm is different because it's easy to use and works well in practice.

CosmWasm wraps Rust binaries as secure smart contracts. The source code is verified by the compiler and the resulting binary contains all of its dependencies statically linked. This prevents attackers from modifying any part of the contract after it has been deployed on-chain.

The CosmWasm development flow

You don't have to write Rust code in order to use CosmWasm. If you're a developer and want to write your own contracts using CosmWasm, you can! As long as your programming language generates a WASM binary with no external dependencies, and defines the correct entry points it will work with CosmWasm. This means you can use any programming language of your choosing. You could write your contract in Go or Python, for example, and then deploy it with CosmWasm.

💡 For more information on CosmWasm navigate to:

Encryption Protocols / Key Management

Secret Network uses both symmetric and asymmetric encryption protocols. Specifically, asymmetric cryptography is used for achieving consensus and sharing secrets between nodes and users, whereas symmetric cryptography is used for input/output encryption with users of Secret Contracts, as well as internal contract state encryption.

Secret Network Protocol uses the Elliptic-curve Diffie-Hellman (ECDH) key exchange mechanism between users and validators. This process involves the user, the Secret Blockchain, as well as the trusted component of the Secret Protocol. It is initiated any time a transaction is sent from the user to the Secret Contract.

The encryption and key derivation logic Secret Network uses are as follows:

• HKDF-SHA256 function for deterministic key derivation;

• ECDH (x25519) function for generating public / private key pairs; and

• AES-128-SIV symmetric encryption scheme.

Symmetric And Asymmetric Encryption

A combination of the above symmetric and asymmetric encryption methods is used to create a safe process for the bootstrapping of the decentralized network, the addition of new SGX nodes, and the encryption of input, output, and state. The management of all the private and public keys may only be shared under specific conditions, and others never leave the SGX instance to ensure private data handling.

Consensus Seed

The Secret Network uses a random number called the “consensus seed” as a parameter to derive a public and private key set used by the Network for encryption purposes. The consensus seed is unknown to any party in the ecosystem and was created at the genesis of the network by the network itself. For deterministic key generation, the network uses a known “salt” which is chosen to be the hash of the Bitcoin halving block.

Transaction encryption

As a transaction is initiated by a user of the network they derive Input Key Material (IKM) using their own private key and the network-generated public key, the network derives the same IKM using the user's public key and the network-generated private key. An encryption key for the transaction is then derived inside the TEE from the IKM, the salt, and a random number generated with the consensus seed. The encryption key is used to encrypt the input specific to this transaction. Only the protocol and the user signing the transaction have access to the encryption key, and therefore access to the input, output, and state related to this specific smart contract computation.

Privacy-Preserving Smart Contract Introduction

Smart contract blockchains are typically public by default. This means that the ledger, the transactions, and the data contained in the smart contract are accessible to anyone. However, this is not the case with Secret Network as it’s the first blockchain that offers programmable privacy through privacy-preserving smart contracts (“Secret Contracts”). “Secret Contracts” have both public and private metadata. Private data on Secret Network is encrypted at input, state, and output and therefore never accessible to any nodes, developers, users, or everyone else.

Programmable Privacy

Programmable privacy is the ability to compute with private data while allowing for not only transfers (transactional privacy) but arbitrarily private complex computations. This allows developers to include sensitive data in their smart contracts without moving off-chain to centralized (and less secure) systems; allowing for truly private and scalable decentralized applications— the true vision of the decentralized web.

To achieve such programmable privacy, Secret Network uses a combination of techniques which will be explained in the further sections of this documentation.

Want to learn about Privacy for smart contracts and the Secret network techstack? Check out the following video series for an introduction:

Full Node Process Epilogue

When a full node resumes network participation, it reads consensus_seed from $HOME/.sgx_secrets/consensus_seed.sealed, does the same key derivation steps as above in steps 2-5.

1. Remote Attestation

The new full node verifies the remote attestation proof of the bootstrap node from genesis.json and creates a remote attestation proof for their own machine to show to the network that the node's Enclave is genuine.

2. Generate Registration Keypair

Using HKDF-SHA256, hkdf_salt and nonce (a 256 bit true random) a private key is derived. From registration_privkey calculate registration_pubkey

3. Authorize Full Node

The node needs to send an secretcli tx register auth transaction with the following inputs:

• The remote attestation proof the node's Enclave is genuine

• registration_pubkey

• 256 bits true random nonce

4. Network Receives Auth

On the consensus layer, inside the enclave of every full node the auth transaction comes in.

The Network validator nodes:

• Receive the secretcli tx register auth transaction

• Verify the remote attestation proof that the new node's Enclave is genuine

5. Generate seed_exchange_key

This key is derived in several steps:

This IKM is never publicly available and protects the Secret network private entropy

In the second step seed_exchange_key is derived using HKDF-SHA256 from seed_exchange_ikm and nonce. When sending the seed_exchange_key to new nodes the Nonce is added as plaintext, it just serves the function of making each seed_exchange_key unique.

6. Sharing consensus_seed with the new node

The seed_exchange_key generated in step 5 is used to encrypt the consensus_seed. The AD for this encryption algorithm is the public key of the new node: new_node_public_key All this logic is done in side the Authorization transaction. secretcli tx register auth outputs the encrypted_consensus_seed

The encrypted output is received by the new full node. The new node now has access to the encrypted_consensus_seed and will have to decrypt to plaintext to receive the consensus_seed

7. New full node generates own seed_exchange_key

The AES-128-SIV encryption key seed_exchange_key is used to decrypt consensus_seed To derive this the reverse logic is followed highlighted in step 5.

seed_exchange_key is derived using HKDF-SHA256 with seed_exchange_ikm and nonce

8. Decrypting encrypted_consensus_seed

encrypted_consensus_seed is encrypted with AES-128-SIV, seed_exchange_key as the encryption key and the public key of the registering node as the ad as the decryption additional data The new node now has all of these parameters inside its Enclave, so it's able to decrypt consensus_seed from encrypted_consensus_seed and then seal consensus_seed to disk at $HOME/.sgx_secrets/consensus_seed.sealed

Bootstrap Process

Secret Network is set up to perform computation while having encrypted state, input and output. The state is encrypted using private keys generated during the network bootstrapping from a consensus_seed. The bootstrap node was the first full node on the network and generated the shared secrets similar to a universal trusted zero knowledge setup.

The bootstrap node first does a remote attestation to prove they are running a genuine SGX enclave with updated software. After registering the bootstrap node handled the initialization of following variables:

• Consensus_seed a true random 256 bit seed used as entropy for generating shareable keypairs between the nodes of the network.

• consensus_seed_exchange_pubkey - consensus_seed_exchange_pubkey an HDKF private key and a matching curve25519 public key for encryption of the random seed and sharing this with other full nodes in the network.

• consensus_io_exchange_pubkey - consensus_io_exchange_pubkey an HDKF private key and a matching curve25519 public key for encrypting transactions IO in the network. Also referenced as the "Secret Network keypair".

• consensus_state_ikm An input keyring material (IKM) for HKDF-SHA256 is used to derive encryption keys for contract state.

• consensus_callback_secret A curve25519 private key is used to create callback signatures when contracts call other contracts

Bootstrap process epilogue

1. Remote attestation

The bootstrap node proves to have a genuine enclave after which it can participate in the network. More information can be found on this page.

2. generate consensus_seed

The bootstrap node is instructed when started to generate a true random 256 bit seed inside the enclave, the consensus_seed.

The consensus_seed is sealed with MRSIGNER to a local file : $HOME/.sgx_secrets/consensus_seed.sealed

// 256 bits
consensus_seed = true_random({ bytes: 32 });

seal({
  key: "MRSIGNER",
  data: consensus_seed,
  to_file: "$HOME/.sgx_secrets/consensus_seed.sealed",
});

2. Generate seed exchange keypair

For the network to start decentralizing the bootstrap node needs to be able to share the consensus_seed. The network can then use the seed to create shared secrets while in the enclave. To securely share the seed the Network uses a DH-key exchange.

Using HKDF-SHA256, hkdf_salt and consensus_seed a private key is derived. From consensus_seed_exchange_privkey calculate consensus_seed_exchange_pubkey

consensus_seed_exchange_privkey = hkdf({
  salt: hkdf_salt,
  ikm: consensus_seed.append(uint8(1)),
}); // 256 bits

consensus_seed_exchange_pubkey = calculate_curve25519_pubkey(
  consensus_seed_exchange_privkey
);

3. Generate IO encryption keypair

Using HKDF-SHA256, hkdf_salt and consensus_seed a private key is derived. - From consensus_io_exchange_privkey calculate consensus_io_exchange_pubkey

consensus_io_exchange_privkey = hkdf({
  salt: hkdf_salt,
  ikm: consensus_seed.append(uint8(2)),
}); // 256 bits

consensus_io_exchange_pubkey = calculate_curve25519_pubkey(
  consensus_io_exchange_privkey
);

4. Generate consensus_state_ikm

Using HKDF-SHA256, hkdf_salt and consensus_seed derive consensus_state_ikm

consensus_state_ikm = hkdf({
  salt: hkdf_salt,
  ikm: consensus_seed.append(uint8(3)),
}); // 256 bits

5. consensus_callback_secret

Using HKDF-SHA256, hkdf_salt and consensus_seed derive consensus_callback_secret

consensus_state_ikm = hkdf({
  salt: hkdf_salt,
  ikm: consensus_seed.append(uint8(4)),
}); // 256 bits

6. add info to Genesis state

Publish to genesis.json:

• The remote attestation proof that the Enclave is genuine

• consensus_seed_exchange_pubkey

• consensus_io_exchange_pubkey

Secret Network leverages TEE technology to do computation with encrypted input, output, and state. The consensus and computation layer of the Secret Network is combined; every validator uses an Intel SGX CPU and processes every transaction.

Private metadata used in Secret Contracts is encrypted before sent to validators for computation. Data is only decrypted inside the TEE of any specific validator, which is inaccessible to them. Computations following the smart contract are done over the decrypted data and the output is encrypted and written to state.

The consensus encryption seed of the network is only stored inside the TEE of each validator node; no entity has access to the encryption keys.

Remote Attestation

Enclaves also go through a detailed registration and attestation process. Specifically, the attestation process which each validator running an SGX enclave must go through ensures the following assertions regarding privacy and correctness:

• The application’s identity

• Its intactness (that it has not been tampered with)

• That it is running securely within an enclave on an Intel SGX enabled platform

For more detailed information on the Intel SGX remote attestation process you can check out this page: Remote attestation

Key Usage Inside SGX

Enclaves generate and contain their private signing/attestation keys, preventing access from any entity outside of each enclave. All data can only be signed using keys associated with specific instruction sets running in each enclave. For more details on key generation and management within enclaves, see our section about encryption.

For our purposes, the attestation key is only used once upon registration. After registration new keys are provisioned to the enclave and used to communicate with the network. This process is described in more detail below.

HKDF-SHA256

To do deterministic key generation inside the SGX enclave Secret Network leverages HDKF-SHA256 1 2. HDKF-SHA256 is a key derivation function for symmetric (private key) encryption. The function generates a 256-bit encryption key from a common public "salt" and a piece of Input Key Material (IKM). The salt1 for the use in the Secret Network encryption schemes is chosen to be the Bitcoin's block halving hash hkdf_salt = 0x000000000000000000024bead8df69990852c202db0e0097c1a12ea637d7e96d

HDKF is commonly used to extract entropy from a larger source and deliver smaller output (eg. an encryption key) as well as expand already existing random output into a larger cryptographic-ally independent output. The deterministic keys coming from HDKF can be shared amongst network participants without revealing the underlying randomness. In the end this symmetric function is used to ensure safety for the pseudo-random consensus_seed and secure the shared secrets of the network participants.

The output of the HDKF is a curve25519 private key, which can be used to derive a public key as well.

Elliptic-curve Diffie-Hellman

Elliptic-curve Diffie-Hellman ECDH (x25519) is a key derivation protocol designed to support assymetric encryption by returning a public-private key pair. ECDH allows for sharing secrets over public channels as one needs the private key to decrypt information while using the public key for sending the encrypted message. These Shared secrets can be used by both parties to then set up subsequent symmetric keys with functions like HDKF as mentioned above. ECDH delivers 256 bits Curve25519 encryption keys which have a probabilistic level of security of 2^128.

ECDH also allows for a special way of generating shared secrets which involves using the private and public key of both participants. Participant A and B can create a shared secret by doing: ecdh(Apriv, Bpub) == ecdh(Bpriv, Apub) , this feature is called "key-exchange" and is the basis of sharing information amongst network participants on Secret Network.

AES-128-SIV - "Rijndael"

Advanced Encyption Standard (AES) is an encryption algorithm slightly varying from the block cipher "Rijndael" set to a fixed 128 bits size block. The algorithm generates 256 bit encryption keys which offer very high security guarantees.

The AES-SIV encryption scheme is a perfect addition to the ECDH keypairs used in SGX enclaves. The combination allows for sharing encrypted data amongst nodes and protecting the private entropy of the protocol. AES-128-SIV was chosen to prevent IV misuse by client libraries. The algorithm does not pad ciphertext which leaks information about the plaintext, in particular its size.

Encryption at deployment of contract

When a contract is executed on chain the state of the contracts needs to be encrypted so that observers can not see the computation that is initialized. The contract should be able to call certain functions inside the enclave and store the contract state on-chain.

A contract can call 3 different functions: write_db(field_name, value), read_db(field_name), and remove_db(field_name) . It is important that the field_name remains constant between contract calls.

We will go over the different steps associated with the encryption of the contract state.

1. Create contract_key

The contract_key is the encryption key for the contract state and is a combination of two values: signer_id || authenticated_contract_key. Every contract has its own unforgeable encryption key. The concatenation of the values is what makes every unique and this is important for several reasons

1. Make sure the state of two contracts with the same code is different

2. Make sure a malicious node runner won't be able to locally encrypt transactions with it's own encryption key, and then decrypt the resulting state with the fake key

so to reiterate, every contract on Secret Network has its own unique and unforgeable encryption key contract_key

This process of creating contract_key is started when the Secret contract is deployed on-chain. First authentication_key is generated using HDKF-SHA256 inside the enclave from the following values:

• consensus_state_ikm

• HDK-salt

• signer_id

signer_id = sha256(concat(msg_sender, block_height));

authentication_key = hkdf({
 salt: hkdf_salt,
 info: "contract_key",
 ikm: concat(consensus_state_ikm, signer_id),
});

From the authentication_key create authenticated_contract_key by calling the hmac-SHA256 hash function with the contract code_hash as hashing data.

This step makes sure the key is unique for every contracts with different code.

authenticated_contract_key = hmac_sha256({
  key: authentication_key,
  data: code_hash,
});

Lastly concat the signer_id and authenticated_contract_key to create contract_key. This step makes it so the key is unforgeable as the key can only be recreated with the current signer_id

contract_key = concat(signer_id, authenticated_contract_key);

2. At execution share contract_key with enclave

Every time a contract execution is called, contract_key should be sent to the enclave. In the enclave, the following verification needs to happen to proof a genuine contract_key

signer_id = contract_key.slice(0, 32);
expected_contract_key = contract_key.slice(32, 64);

authentication_key = hkdf({
  salt: hkdf_salt,
  info: "contract_key",
  ikm: concat(consensus_state_ikm, signer_id),
});

calculated_contract_key = hmac_sha256({
  key: authentication_key,
  data: code_hash,
});

assert(calculated_contract_key == expected_contract_key);

3. Callback function logic

write_db(field_name, value)

encryption_key = hkdf({
  salt: hkdf_salt,
  ikm: concat(consensus_state_ikm, field_name, contract_key),
});

encrypted_field_name = aes_128_siv_encrypt({
  key: encryption_key,
  data: field_name,
});

current_state_ciphertext = internal_read_db(encrypted_field_name);

if (current_state_ciphertext == null) {
  // field_name doesn't yet initialized in state
  ad = sha256(encrypted_field_name);
} else {
  // read previous_ad, verify it, calculate new ad
  previous_ad = current_state_ciphertext.slice(0, 32); // first 32 bytes/256 bits
  current_state_ciphertext = current_state_ciphertext.slice(32); // skip first 32 bytes

  aes_128_siv_decrypt({
    key: encryption_key,
    data: current_state_ciphertext,
    ad: previous_ad,
  }); // just to authenticate previous_ad
  ad = sha256(previous_ad);
}

new_state_ciphertext = aes_128_siv_encrypt({
  key: encryption_key,
  data: value,
  ad: ad,
});

new_state = concat(ad, new_state_ciphertext);

internal_write_db(encrypted_field_name, new_state);

read_db(field_name)

encryption_key = hkdf({
  salt: hkdf_salt,
  ikm: concat(consensus_state_ikm, field_name, contract_key),
});

encrypted_field_name = aes_128_siv_encrypt({
  key: encryption_key,
  data: field_name,
});

current_state_ciphertext = internal_read_db(encrypted_field_name);

if (current_state_ciphertext == null) {
  // field_name doesn't yet initialized in state
  return null;
}

// read ad, verify it
ad = current_state_ciphertext.slice(0, 32); // first 32 bytes/256 bits
current_state_ciphertext = current_state_ciphertext.slice(32); // skip first 32 bytes
current_state_plaintext = aes_128_siv_decrypt({
  key: encryption_key,
  data: current_state_ciphertext,
  ad: ad,
});

return current_state_plaintext;

remove_db(field_name)

Very similar to read_db.

encryption_key = hkdf({
  salt: hkdf_salt,
  ikm: concat(consensus_state_ikm, field_name, contract_key),
});

encrypted_field_name = aes_128_siv_encrypt({
  key: encryption_key,
  data: field_name,
});

internal_remove_db(encrypted_field_name);

Transaction encryption unlike contract state encryption has two parties who need data access. The scheme therefore makes use of the DH-key exchange as described in the previous section to generate a shared encryption key. This symmetric tx_encryption_key is unique for every transaction and can be used by both the network and the user to verify the completed transactions.

1. Generation of shared secret - user side

Using the Eliptic-Curve Diffie Hellman key exchange (ECDH) the user generates a shared secret from consensus_io_exchange_pubkey and tx_sender_wallet_privkey.

tx_encryption_ikm = ecdh({
  privkey: tx_sender_wallet_privkey,
  pubkey: consensus_io_exchange_pubkey, // from genesis.json
}); // 256 bits

2. Generate tx_encryption_key - user side

The user then generates a shared tx_encryption_key using HKDF-SHA256 and the tx_encryption_ikm generated in step 1. The pseudo-random HDKF is used to ensure deterministic consensus across all nodes.

The random component comes from a 256-bit nonce so that each transaction has its own encryption key, An AES-256-GCM encryption key is never used twice.

nonce = true_random({ bytes: 32 });

tx_encryption_key = hkdf({
  salt: hkdf_salt,
  ikm: concat(tx_encryption_ikm, nonce),
}); // 256 bits

3. Encrypt transaction - user side

After initiating a transaction the user encrypts the input data with the shared transaction encryption key, using an AES-256-GCM authenticated encryption scheme.

The input (msg) to the contract is always prepended with the sha256 hash of the contract's code. This is meant to prevent replaying an encrypted input of a legitimate contract to a malicious contract, and asking the malicious contract to decrypt the input.

In this attack example the output will still be encrypted with a tx_encryption_key that only the original sender knows, but the malicious contract can be written to save the decrypted input to its state, and then via a getter with no access control retrieve the encrypted input.

ad = concat(nonce, tx_sender_wallet_pubkey);

codeHash = toHexString(sha256(contract_code));

encrypted_msg = aes_128_siv_encrypt({
  key: tx_encryption_key,
  data: concat(codeHash, msg),
  ad: ad,
});

tx_input = concat(ad, encrypted_msg);

4. Generation tx_ecryption_key - network side

The enclave uses ECDH to derive the same tx_encryption_ikm from the tx_sender_wallet_pubkey and the consensus_io_exchange_privkey. The network then derives the tx_encryption_key from the publicly signed nonce and this shared secret using HDKF.

Within the trusted component the transaction input is decrypted to plaintext.

nonce = tx_input.slice(0, 32); // 32 bytes
tx_sender_wallet_pubkey = tx_input.slice(32, 32); // 32 bytes, compressed curve25519 public key
encrypted_msg = tx_input.slice(64);

tx_encryption_ikm = ecdh({
  privkey: consensus_io_exchange_privkey,
  pubkey: tx_sender_wallet_pubkey,
}); // 256 bits

tx_encryption_key = hkdf({
  salt: hkdf_salt,
  ikm: concat(tx_encryption_ikm, nonce),
}); // 256 bits

codeHashAndMsg = aes_128_siv_decrypt({
  key: tx_encryption_key,
  data: encrypted_msg,
});

codeHash = codeHashAndMsg.slice(0, 64);
assert(codeHash == toHexString(sha256(contract_code)));

msg = codeHashAndMsg.slice(64);

BREAK - Data output formatting

The output must be a valid JSON object, as it is passed to multiple mechanisms for final processing:

• Logs are treated as Tendermint events

• Messages can be callbacks to another contract call or contract init

• Messages can also instruct sending funds from the contract's wallet

• A data section which is free-form bytes to be interpreted by the client (or dApp)

• An error section

Here is an example output for an execution:

{
"ok": {
  "messages": [
	{
	  "type": "Send",
	  "to": "...",
	  "amount": "..."
	},
	{
	  "wasm": {
		"execute": {
		  "msg": "{\"banana\":1,\"papaya\":2}", // need to encrypt this value
		  "contract_addr": "aaa",
		  "callback_code_hash": "bbb",
		  "send": { "amount": 100, "denom": "uscrt" }
		}
	  }
	},
	{
	  "wasm": {
		"instantiate": {
		  "msg": "{\"water\":1,\"fire\":2}", // need to encrypt this value
		  "code_id": "123",
		  "callback_code_hash": "ccc",
		  "send": { "amount": 0, "denom": "uscrt" }
		}
	  }
	}
  ],
  "log": [
	{
	  "key": "action", // need to encrypt this value
	  "value": "transfer" // need to encrypt this value
	},
	{
	  "key": "sender", // need to encrypt this value
	  "value": "secret1v9tna8rkemndl7cd4ahru9t7ewa7kdq87c02m2" // need to encrypt this value
	},
	{
	  "key": "recipient", // need to encrypt this value
	  "value": "secret1f395p0gg67mmfd5zcqvpnp9cxnu0hg6rjep44t" // need to encrypt this value
	}
  ],
  "data": "bla bla" // need to encrypt this value
}
}

Please Note!

• on a Contract message, the msg value should be the same msg as in our tx_input, so we need to prepend the nonce and tx_sender_wallet_pubkey just like we did on the tx sender above

• On a Contract message, we also send a callback_signature, so we can verify the parameters sent to the enclave (read more here: ......)

callback_signature = sha256(consensus_callback_secret | calling_contract_addr | encrypted_msg | funds_to_send)

• For the rest of the encrypted outputs we only need to send the ciphertext, as the tx sender can get consensus_io_exchange_pubkey from genesis.json and nonce from the tx_input that is attached to the tx_output with this info only they can decrypt the transaction details.

• Here is an example output with an error:

{
"err": "{\"watermelon\":6,\"coffee\":5}" // need to encrypt this value
}

• An example output for a query:

{
"ok": "{\"answer\":42}" // need to encrypt this value
}

5. Writing output - network side

The output of the computation is encrypted using the tx_encryption_key

// already have from tx_input:
// - tx_encryption_key
// - nonce


if (typeof output["err"] == "string") {

  encrypted_err = aes_128_siv_encrypt({
    key: tx_encryption_key,
    data: output["err"],
  });
  
  output["err"] = base64_encode(encrypted_err); // needs to be a JSON string
} 


else if (typeof output["ok"] == "string") {

  // query
  // output["ok"] is handled the same way as output["err"]...
  
  encrypted_query_result = aes_128_siv_encrypt({
    key: tx_encryption_key,
    data: output["ok"],
  });
  
  output["ok"] = base64_encode(encrypted_query_result); // needs to be a JSON string
} 


else if (typeof output["ok"] == "object") {

  // init or execute
  // external query is the same, but happens mid-run and not as an output
  
  for (m in output["ok"]["messages"]) {
    if (m["type"] == "Instantiate" || m["type"] == "Execute") {
    
      encrypted_msg = aes_128_siv_encrypt({
        key: tx_encryption_key,
        data: concat(m["callback_code_hash"], m["msg"]),
      });

      // base64_encode because needs to be a string
      // also turns into a tx_input so we also need to prepend nonce and tx_sender_wallet_pubkey
      
      m["msg"] = base64_encode(
        concat(nonce, tx_sender_wallet_pubkey, encrypted_msg)
      );
    }
  }

  for (l in output["ok"]["log"]) {
    // l["key"] is handled the same way as output["err"]...
    
    encrypted_log_key_name = aes_128_siv_encrypt({
      key: tx_encryption_key,
      data: l["key"],
    });
    
    l["key"] = base64_encode(encrypted_log_key_name); // needs to be a JSON string

    // l["value"] is handled the same way as output["err"]...
    
    encrypted_log_value = aes_128_siv_encrypt({
      key: tx_encryption_key,
      data: l["value"],
    });
    
    l["value"] = base64_encode(encrypted_log_value); // needs to be a JSON string
  }

  // output["ok"]["data"] is handled the same way as output["err"]...
  
  encrypted_output_data = aes_128_siv_encrypt({
    key: tx_encryption_key,
    data: output["ok"]["data"],
  });
  
  output["ok"]["data"] = base64_encode(encrypted_output_data); // needs to be a JSON string
}

return output;

6. Receiving output - user side

The transaction output is written to the chain and only the wallet with the right tx_sender_wallet_privkey can derive tx_encryption_key. To everyone else but the tx signer the transaction data will be private.

Every encrypted value can be decrypted by the user following:

// output["err"]
// output["ok"]["data"]
// output["ok"]["log"][i]["key"]
// output["ok"]["log"][i]["value"]
// output["ok"] if input is a query

encrypted_bytes = base64_encode(encrypted_output);

aes_128_siv_decrypt({
  key: tx_encryption_key,
  data: encrypted_bytes,
});

• For output["ok"]["messages"][i]["type"] == "Contract", output["ok"]["messages"][i]["msg"] will be decrypted in by the consensus layer when it handles the contract callback

Why SGX?

Intel SGX is one of the most used and widely available implementations of Trusted Execution Environments (TEEs). Secret Network has selected this technology for the initial version of the Secret Network for two main reasons: Usability & Security.

Usability

SGX is more performant and more flexible than other solutions for privacy-preserving computation. The Secret Network is building a platform for decentralized, general-purpose private computation. This requires a privacy solution that can enable a wide range of use cases. It also requires computations to be on par, performance-wise, with non-privacy preserving computation, so that speed does not limit application usability.

Security

SGX is one of the most widely adopted technologies for TEEs, it is also battle-hardened. Attacks are often theoretical, executed in laboratory settings, and are rapidly addressed by Intel. Many high-value targets exist that have not been compromised. No privacy solution is 100% secure, but we believe the security guarantees provided by Intel SGX are adequate for a wide range of use cases.

Secret Network only allows for Intel SGX chips, AMD-SEV or other TEE technologies are not usable for running nodes on the network.

SGX-ME And SGX-SPS

SGX comes in 2 forms; SGX-ME and SGX-SPS. SGX-ME (management engine) uses small extra chips to manage functions related to the enclave such as memory and energy management. SGX-SPS (Server Platform Services) allows the bypassing of the ME chip. To further reduce the number of possible attack vectors on the network, Secret Network has opted to only use SGX-SPS. Hence, all attack vectors of the ME chip do not apply to Secret Network.

Furthermore, each full node on Secret Network creates an attestation report that proves that their CPU is using the latest firmware/microcode (processor firmware) upgrades before it registers. The entire network verifies the attestation report of the new node on-chain, to ensure that node operators cannot decrypt anything. Once the new node gets the shared key of the consensus they become part of the consensus and are able to process computations and transactions in parallel to the network.

From Genesis Seed to Seed Rotation: an Overview

Secret Network recently upgraded to version 1.7.1, which rotated the network consensus seed during the upgrade.

A consensus seed is a true random 256 bit seed that is used as entropy for generating shareable keypairs between the nodes of the network.

Previously, the consensus seed remained unchanged ever since the network’s inception–the network state was encrypted using private keys generated during the network bootstrapping from a consensus seed, similar to a universal trusted zero knowledge setup. However, if anyone were to gain access to this seed they would have the master key to decrypt the state of the entire network. Thus, Secret Network has introduced consensus seed rotation in order to increase network security.

Consensus Seed Rotation

In order to protect against potential future breaches, Secret Network developed a two-part protocol for changing the consensus seed:

1. Rotate the current seed (The "Genesis" seed) and change the encryption scheme

2. Implement contract state migration and allow seed rotation on upgrade (currently in development)

It is important to note that the upgrade to consensus seed rotation does not change the state (and the consensus seed) of the network prior to the upgrade. This means that the new encryption scheme must be able to distinguish between values that were encrypted with the genesis seed and those that will be encrypted with future seeds. To this end, the following features were implemented:

• A way to distinguish between values that were encrypted with the genesis seed and those that will be encrypted with future seeds

• The ability to iterate over all of the keys for a specific contract using CosmWasm iterators (currently in development)

• The ability to decrypt state keys, rotate the seed, and decrypt and re-encrypt all keys & values in the state

Creating a New Seed

In order to rotate the Genesis seed, a new seed must be created that will be shared with all current nodes as well as new nodes. To this end, Secret Labs updated all of the existing nodes with the new seed and every new node that joins the network will contain 2 consensus seeds (The genesis and the current) and will use them both based on the encrypted value.

The new seed can be received via three methods:

1. On upgrade: When upgrading to 1.7.1, the node will identify that the current seed is missing and will communicate with Secret Labs’ seed service in order to obtain the seed

2. On Registration: On registration, both the current and the genesis seed will be passed to the newly registered node

3. On Bootstrap: Boostrap will access the seed service unless the "use_seed_service_on_bootstrap" feature is off (Which is the default state in localsecret). If so, it will generate one instead.

Previous Encryption Scheme

In the previous encryption scheme, the key and the value were stored as follows:

New Encryption Scheme

In the new encryption scheme, the plaintext key is no longer necessary in order to decrypt the value. The encrypted value also looks a bit different in the new scheme:

This new encryption scheme ensures that:

• the encrypted_state_key encrypts differently between different keys

• The salt will verify that on different instances, the same value is encrypted differently for the same key. The salt is the current block's timestamp and the msg id, which is a counter of the messages and allows for different values between different messages in the same block.

Node to Service Protocol

In order to authenticate a node, the node first sends an attestation report to the designated /authenticate endpoint as the request body. The server then responds with a challenge, which is a randomly generated 4-byte value that is linked to the public key of the node. The node then creates a new attestation report that incorporates the challenge into its quote, which proves that the node can generate new attestation reports certified by Intel while also rendering old certificates invalid. Subsequently, the node transmits this new attestation report to the /seed/[id] endpoint, where the ID represents the desired seed. Upon receiving the attestation report, the server verifies it and sends the seed to the node.

The port of the service is 4487 and there are 2 DNS names that are used.

On MainNet - sss.scrtlabs.com

On Pulsar - sssd.scrtlabs.com

Conclusion

Secret Network has implemented consensus seed rotation in the upgrade to version 1.7.1. Previously, the consensus seed remained unchanged since the network's inception, but this posed a security risk as anyone with access to the seed would have the master key to decrypt the entire network's state. The new consensus seed rotation includes a two-part protocol to change the genesis seed and encryption scheme, and implement contract state migration to allow seed rotation on upgrade. The upgrade does not change the network state prior to the upgrade, so the new encryption scheme distinguishes between values encrypted with the genesis seed and those encrypted with future seeds. Secret Labs updated all existing nodes with the new seed and new nodes joining the network will have both the genesis and current seeds, using them based on the encrypted value. These updates increase the security of Secret Network by protecting against potential future breaches.

The main difference when it comes to Cosmos compared to virtual-machine blockchain, is the application-specific blockchain concept. Developers can build from scratch their application specific blockchain on top of Tendermint through ABCI protocol. Cosmos SDK is the framework offering a bank of independent modules for implementing the application state machine, ABCI, service routers to route messages between modules, and a flavor of features like governance, staking, slashing, etc …

Cosmos Virtual Machine

Below a figure showing the architecture differences between a VM blockchain and Cosmos:

A virtual-machine interprets Smart Contracts to change the state of the underlying blockchain state machine. It’s developer friendly and easy to use to deploy applications but comes with certain limitations:

• Specific programming language accepted by the VM

• VM limited set of functions and lack of flexibility

• Smart Contracts are all run by the same virtual machine restraining performance as all application compete for block resources

• Limited sovereignty, meaning that the application is dependent of the underlying blockchain governance decision

Development framework

In Cosmos, developers have all the keys to develop a sovereign, secure, flexible and tailor made application specific blockchain.

Cosmos SDK allows developers to tweak, if needed, the framework or the consensus engine or any modules to match their application/network requirements.

As the application is not competing with others for blockspace or is limited by the VM computation, the performance is enhanced and only limited by the state-machine itself.

In terms of security, developers are not constrained by the VM cryptographic functions or any VM exploitable mechanisms and can rely on their own cryptography or audited libraries.

Conclusion

In conclusion Cosmos SDK is giving an easy and fast way to bootstrap an application specific blockchain relying on an efficient and proven technology without tradeoffs on security and sovereignty and with access to an extensive modules library.

💡 For more information about the Cosmos SDK: High-level Overview | Cosmos SDK & Main Components of the Cosmos SDK

Trusted Execution Environments are essentially stateless. To preserve information that’s stored in an enclave, it must be explicitly sent outside the enclave to untrusted memory. SGX provides a capability called which encrypts enclave data in the enclave using an encryption key derived from the CPU. This encrypted data block can only be decrypted, or unsealed, on the same system. This SGX-specific method for storing data is not used to store computation input/output data in the Secret Network. It is used to store the enclave’s signing key.

We seal the signing key because this key is created during the remote attestation process. We do not want the enclave to be required to perform between each computation. If the enclave fails for some reason, and the key is lost, the worker would be obligated to go through the remote attestation process again. The only way to store persistent data from the enclave is through sealing.

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, !

Secret Contracts are enabled by the “compute” module of the Cosmos SDK, and execute over plaintext while still allowing for encrypted inputs, outputs, and states because of trusted and verifiable computations. Consensus with an encrypted state is reached by using shared secrets amongst the validator nodes of the network.

In this part of the documentation, we highlight the flow of data for interactions on the secret network and dive into the design of Secret Contracts and their differentiations from standard CosmWasm contracts.

Public binary

A Secret Contract’s code is always deployed publicly on-chain, so users and developers know exactly what code will be executed on submitted data. However, the data that is submitted is encrypted, it cannot be read by a developer, anyone observing the chain, or anyone running a node. If the behavior of the code is trusted (which is possible because it is recorded on chain), a user of Secret Contracts obtains strong privacy guarantees.

Encrypted input, output, state

The encrypted data can only be accessed from within the “trusted execution environment”, or enclave, that the compute module requires each validator to run. The computation of the Secret Contract is then performed, within this trusted enclave, where the data is decrypted. When the computation is completed, the output is encrypted and recorded on-chain.

The CosmWasm framework

Secret contracts are an altered version of the CosmWasm Rust based smart contract framework and share many resemblance. The contracts written in Rust compile to a Wasm binary that is than run by the Wasmd module of the cosmos SDK. The version of Secret is altered in such a way that all executions are done inside the secure enclave requiring additional data verification and more. This also means queries of the contract state or contract execution are permissioned to only the signer of the transaction themselves. Contract state queries requiring opening up the VM in the enclave and are therefore more intensive to run than generic plaintext cosmos-sdk queries.

Remote attestation, an advanced feature of Intel SGX, is the process of proving an enclave is established in a secure hardware environment. A remote party should be able to verify that the right application is running inside an enclave on an Intel SGX enabled platform.

Remote attestation provides verification for three things:

• The application’s identity

• Its intactness (that it has not been tampered with)

• That it's running securely within an enclave on an Intel SGX enabled platform

Attestation is necessary in order to make remote access secure because an enclave’s contents may have to be accessed remotely, not from the same platform []

Steps to make a valid proof

The attestation process consists of seven stages, encompassing several actors, namely the service provider (referred to as a challenger) on one platform; and the application, the application’s enclave, the Intel-provided Quoting Enclave (QE), and Provisioning Enclave (PvE) on another platform. A separate entity in the attestation process is Intel Attestation Service (IAS), which carries out the verification of the enclave [][][].

In short, the seven stages of remote attestation comprise of making a remote attestation request (stage 1), performing a local attestation (stages 2-3), converting the local attestation to a remote attestation (stages 4-5), returning the remote attestation to the challenger (stage 6), and verifying the remote attestation (stage 7) [][].

Secure communication channel

Intel Remote Attestation also includes the establishment of a secure communication session between the service provider and the application. This is analogous to how the familiar TLS handshake includes both authentication and session establishment.

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.

The Secret smart contract 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.

This is the source code for the full stack application, and you can use the live dApp at this web address 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

This tutorial assumes that you've already learned how to compile, upload, and instantiate a Secret smart contract to the Secret testnet and now you will learn how to connect your instantiated smart contract to a frontend library, namely, React.js.

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

In order to execute the Secret millionaire contract, users must first be able to connect to their Keplr wallet. To see a generalized approach to connecting to Keplr wallet with Secret.js, you can review the Secret.js docs here. However, for our application you will learn how to connect to Keplr with React.js so that the user's wallet can control every page of your app.

Connect Wallet function

Before we proceed, review the ConnectWallet() function:

 async function connectWallet() {
    try {
      if (!window.:) {
        console.log("install keplr!");
      } else {
        await setupKeplr(setSecretjs, setSecretAddress);
        localStorage.setItem("keplrAutoConnect", "true");
        console.log(secretAddress);
      }
    } catch (error) {
      alert(
        "An error occurred while connecting to the wallet. Please try again."
      );
    }
  }

This function awaits SetupKeplr(), an asynchronous function which enables Secret Network on Keplr, retrieves the user's account information from Keplr, creates a Secret Network client with this information, and then sets the secretjs instance and secretAddress with these details so that we can then share this data with the rest of our application. Notice that when we establish the Secret Network client with Secret.js we are also specifying the url and chainId of the client, which in this case is the url + chainId for Secret testnet:

    const chainID = "pulsar-3",
    const url = "https://api.pulsar.scrttestnet.com",
    
    const accounts = await keplrOfflineSigner.getAccounts();

    const secretAddress = accounts[0].address;

    const secretjs = new SecretNetworkClient({
      url: url,
      chainId: chainId,
      wallet: keplrOfflineSigner,
      walletAddress: secretAddress,
      encryptionUtils: window.getEnigmaUtils(SECRET_CHAIN_ID),
    });

    setSecretAddress(secretAddress);
    setSecretjs(secretjs);
  }

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

The Secret Millionaire contract is designed such that when a millionaire's net worth is submitted, the contract saves the first two entries and then returns an error for subsequent attempts until a reset. The reset operation resets the contract's state back to its initial condition, where no millionaires are registered.

Because the Secret smart contract requires two millionaires to be submitted at any given time, it would be an improved UI experience if the user could submit two millionaires simultaneously, rather than having to execute two separate transactions. We are able to implement this functionality with Secret.js using MsgExecuteContract and the broadcast method:

let submit_net_worth = async (millionaire1, millionaire2) => {
    const millionaire1_tx = new MsgExecuteContract({
      sender: secretAddress,
      contract_address: contractAddress,
      msg: {
        submit_net_worth: {
          name: millionaire1.name,
          worth: parseInt(millionaire1.networth),
        },
      },
      code_hash: contractCodeHash,
    });

    const millionaire2_tx = new MsgExecuteContract({
      sender: secretAddress,
      contract_address: contractAddress,
      msg: {
        submit_net_worth: {
          name: millionaire2.name,
          worth: parseInt(millionaire2.networth),
        },
      },
      code_hash: contractCodeHash,
    });
    const txs = await secretjs.tx.broadcast(
      [millionaire1_tx, millionaire2_tx],
      {
        gasLimit: 300_000,
      }
    );
    console.log(txs);
  };

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:

const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      setMillionaire1({ name: name1, networth: networth1 });
      setMillionaire2({ name: name2, networth: networth2 });

      // Call submit_net_worth with the updated values
      await submit_net_worth(
        { name: name1, networth: networth1 },
        { name: name2, networth: networth2 }
      );
      // let myQuery = [];
      await query_net_worth(myQuery);

      setRicherModalOpen(true);
      setShowRicherButton(false);
    } catch (error) {
      alert("Please approve the transaction in keplr.");
    }
  };

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:

  const resetSubmit = async (e) => {
    e.preventDefault();
    try {
      await reset_net_worth();
      setResetModalOpen(true);
      setShowRicherButton(true);
    } catch (error) {
      alert("Please connect your wallet by selecting the wallet icon.");
    }
  };

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.

  let query_net_worth = async (myQuery) => {
    let query = await secretjs.query.compute.queryContract({
      contract_address: contractAddress,
      query: {
        who_is_richer: {},
      },
      code_hash: contractCodeHash,
    });

    myQuery.push(query);
  };

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

You now have all of the tools you need to create a decentralized full stack application on Secret Network. In this tutorial you learned how to write React.js functions to connect to Keplr wallet, submit simultaneous transactions and reset net worth data, and query a Secret smart contract for the wealthier party. If you have further questions as you continue to develop on Secret Network, please join the weekly Monday developer call on Discord at 1pmET.

What Is Instantiation?

The Instantiate function is the function that will run once (and only once) immediately upon initializing your smart contract after uploading it to the network. It is meant to set up the smart contract with all vital code that must be run first before any users have the ability to execute the contract. For those familiar with a solidity constructor on Ethereum, Instantiate serves the exact same purpose.

If you have any vital info to save to the state such as Config parameters or an admin/operator address to name a few options, those should probably be specified here. In addition, if your contract requires entropy for randomization or needs to register to receive a SNIP-20 token for payment, those operations should also be performed here, as other execution messages will rely on that data to be already instantiated.

Instantiate takes four arguments:

• "deps": allows the contract to interact with the outside world by reading and updating the contract state, accessing other contract states, and using helper functions to work with contract addresses.

• "env": is an object that represents the current state of the blockchain when the contract is executed, including the blockchain's height, timestamp, and the address of the contract being called.

• "info": metadata about the message that triggered the contract's execution, such as the sender's address and the native tokens that were sent with the message.

• "msg": is the message that triggers the contract's execution, which is currently represented by the "Empty" type in the codeblock above.

Smart contracts on Secret Network follow the widely used framework. The framework is built as a module for the Cosmos SDK and allows developers to build smart contracts with which compile to (Wasm). This type of efficient and fast binary, combined with the power of a low-level typed coding language, makes CosmWasm a secure and efficient way for developers to write smart contracts. Contracts on Secret have a public binary just like any other smart contract network, only the contract input, output and state is encrypted. The contracts are executed in the Wasm VM as deployed via the Wasmd Cosmos SDK module on the Secret blockchain.

Secret Contracts slightly differ from any standard CosmWasm implementation as they handle encrypted data, secure enclaves, and the key design around that. Secret currently emulates CosmWasm v1.1.9 and is completely compatible over IBC with other V1.0+ Cosmos Smart contract networks.

The components of a CosmWasm contract

A Secret contract has 4 different components as listed below each serving a different function. A deeper overview of the implementation of these 4 components/files is given in the Contract-components section.

Execution Messages are contract messages that trigger the execution of a smart contract and perform specific operations, such as updating the contract state or transferring tokens. If you’re familiar with RPC or AJAX, you can think of execution messages as the code that runs when a remote procedure is called. On Secret Network, execution messages are usually designed to be functions that run as quickly as possible and exit as early as possible when any errors are encountered, as this will help save gas. You can learn more about contract optimization .

The standard practice on Secret Network is to have an enum with all the valid message types and reject all messages that don’t follow the usage pattern dictated in that enum; this enum is conventionally called ExecuteMsg and is usually in a file called msg.rs

As mentioned earlier, the standard way to choose what the contract should execute is to look at which ExecuteMsg is passed to the function. Let’s look at an example.

In this simple example, the code looks at the message passed, if the passage is the Increment message, it calls the function try_increment, otherwise, if the message is the Reset message, it calls the function try_reset with the count.

You may have noticed that the execution message takes two arguments in addition to the msg: deps and env. Let’s look at those more closely.

env

As the name perhaps implies, env contains all the information about the environment the contract is running in, but what does that mean exactly? On Secret Network the properties available in the Env struct are as follows:

• block: this contains all the information about the current block. This is the block height (height), the current time as a unix timestamp (time) and the chain id (chain_id) such as secret-4 or pulsar-3.

• message: contains information that was sent as part of the payload for the execution. This is the sender, or the wallet address of the person that called the handle function and sent_funds which contains a vector of native funds sent by the caller (SNIP-20s are not included).

• contract: contains a property with the contract’s address.

• contract_code_hash: this is a String containing the code hash of the current contract, it’s useful when registering with other contracts such as SNIP20s or SNIP721s or when working on a factory contract.

Now that you have an overview on what all those properties are, let’s take a look at a simple Execution Message.

Example ExecutionMsg

The execution message above reads the state from the storage(Deps) and increments the count property by one, then prints out the new count, if successful.

The developers of this contract opted for using storage singletons. A storage singleton can be thought as a prefixed typed storage solution with simple-to-use methods. This allows the developer to define a structure for the data that needs to be stored and handles encoding end decoding it, so the developer doesn’t have to think about it. This is how it’s implemented in this contract:

The config function returns a singleton over the config key using the State struct as its type, this means that when reading and writing data from the storage, the singleton automatically serializes or deserializes the State struct.

Response

You may have noticed that the return type for a handle message is Response. Let's take a look at how Response is defined:

In CosmWasm, the Ok result and the Response object are essential parts of handling contract execution and signaling the outcome to the blockchain. Here's a breakdown of how these work:

Ok Result in CosmWasm

In Rust (and by extension, CosmWasm), functions that interact with the blockchain often return a Result type. This is a way to express whether the function was successful or if it encountered an error.

• Result<T, E>: A Result can either be:

  • Ok(T): Signifying the function executed successfully and returns a value of type T.

  • Err(E): Signifying that an error of type E occurred.

In the context of CosmWasm, the Ok result generally signifies that a contract's execution completed successfully, returning a Response object.

For example:

This line means that the contract execution was successful, and it returns a default Response. In CosmWasm, we use StdResult<Response> for contract execution functions.

Why Is Prefixed Storage Needed?

Before we understand what the PrefixedStorage struct is, we should first understand the problem they attempt to solve. We may be tempted to think that the key-value model as described in Storage solves all our storage needs. And we'd technically be correct in thinking that. It is possible to efficiently store vast amounts of user data by just using the methods described in that page. However, we will see that doing this would be cumbersome for the developer in many cases. That's why there are many additional storage structures built on top of the methods described in Storage. Prefixed storage is an additional structure built on top of these methods for the convenience of the developer.

The Problem

We will go over a storage problem and discuss how we might tackle it with the methods we learnt in Storage to get to the root of what prefixed storage actually is. Suppose that we have contract that stores a different password (String) for each wallet address that interacts with it (so that the wallets can later give that password when querying the contract). How would we want to store all these passwords so that they can be checked when it is time for queries?

The Naive Approach

Our first approach might be to use a hashmap that stores all the passwords, and save it as binary using the methods we already know. So we would add the following lines to the init

let passwords: HashMap<&[u8], String> = HashMap::new();

save(&mut deps.storage, PASSWORDS_KEY, &passwords)?;

And then we can proceed to load, and add each users' password whenever a user sends the create_password HandleMsg. Note that I'm assuming we would generate the &[u8] key for the hashmap from the user's wallet address. This approach has a huge problem! That is whenever we want to add another wallet's password to the hashmap, we must load the entire hashmap with all the passwords stored inside it. This will increase gas costs as we gain thousands of users. Moreover, loading the hashmap for queries will strain the node.

The Reasonable Approach

We now realize that we can actually generate&[u8] storage keys for each user wallet and save the password directly to deps.storage as described in Storage. This way, we can use may_load to check if a user has a password, and if he does, learn what it is without loading all the other passwords. Then we would use the following lines of code to save a password

let key: &[u8] = env.message.sender.to_string().as_bytes();
save(&mut deps.storage, key, &msg.password)?;

This method does work! However, what if we want to save additional things that is associated to each user, such as token balances. Then using save on the same key would overwrite our previous data. The solution is to add a prefix to the storage key so that we know it belongs to the password property. One way to implement this is the following:

let prefix: String = "passwords".to_string();
let key: &[u8] = ( prefix + env.message.sender.to_string()).as_bytes();
save(&mut deps.storage, key, &msg.password)?;

This works but can be cumbersome and ugly, especially if you need to build more functionalities around this idea. This is exactly what prefixed storage does in the background! Prefixed Storage is built to solve this problem while hiding away all the ugliness.

What Is Prefixed Storage?

PrefixedStorage is a struct that keeps track of all the storage keys that are used to store various data under a shared namespace similar to described above. Prefixed storage is often used to keep track of storage keys of deps.storage, but it can in fact be used to store the keys of other storage structures.

Example

Let's solve the password problem that was mentioned above with prefixed storage. The solution to this problem resembles viewing keys for permissioned viewing. You will learn more about this in the coming sections. We first define a namespace (prefix) in state.rs.

pub const PREFIX_PASSWORDS: &[u8] = b"passwords";

The idea then is that all the wrapper functions that we've learnt in Storage also work on prefixed storage. We will only demonstrate save and may_load by example.

Saving To Prefixed Storage

We would instantiate a mutable PrefixedStorage object using the following lines of code to save a new password

let mut password_store = PrefixedStorage::new(PREFIX_PASSWORDS, &mut deps.storage);
let key: &[u8] = env.message.sender.to_string().as_bytes();
save(&mut password_store, key, &msg.password)?;

The reason why we can use the same wrapper functions is because Prefixed Storage implements the Storage trait, even though most of what it's doing is to add a prefix on top of the keys we provide to it.

Loading From Prefixed Storage

We may use both load and may_load We may load data from a mutable Prefixed Storage instance with the following lines of code