Merge pull request #1187 from dfinity/jessiemongeon1-patch-18

jessiemongeon1 · web-flow · commit 4c76dee60a32 · 2025-06-24T08:17:55.000-05:00
add: Deploy to ICP Ninja + Standardize README
diff --git a/motoko/threshold-ecdsa/README.md b/motoko/threshold-ecdsa/README.md
@@ -1,6 +1,6 @@
 # Threshold ECDSA sample
 
-We present a minimal example canister smart contract for showcasing the [threshold ECDSA](https://internetcomputer.org/docs/current/developer-docs/integrations/t-ecdsa) API.
+We present a minimal example canister smart contract for showcasing the [threshold ECDSA](https://internetcomputer.org/docs/building-apps/network-features/signatures/t-ecdsa) API.
 
 The example canister is a signing oracle that creates ECDSA signatures with keys derived from an input string.
 
@@ -12,59 +12,13 @@ More specifically:
 
 This tutorial gives a complete overview of the development, starting with downloading the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install), up to the deployment and trying out the code on the IC mainnet.
 
-> [!TIP]
-> This walkthrough focuses on the version of the sample canister code written in [Motoko](https://internetcomputer.org/docs/current/developer-docs/backend/motoko/index.md) programming language, but no specific knowledge of Motoko is needed to follow along. There is also a [Rust](https://github.com/dfinity/examples/tree/master/rust/threshold-ecdsa) version available in the same repo and follows the same commands for deploying.
+## Deploying from ICP Ninja
 
-## Local development
+[![](https://icp.ninja/assets/open.svg)](https://icp.ninja/editor?g=https://github.com/dfinity/examples/tree/master/motoko/threshold-ecdsa)
 
-### Prerequisites
-This example requires an installation of:
+### 1. Update source code with the right key ID
 
-- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) v0.11.0 or newer.
-- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples`
-
-Begin by opening a terminal window.
-
-### Step 1: Setup the project environment
-
-Navigate into the folder containing the project's files and start a local instance of the Internet Computer with the commands:
-
-```bash
-cd examples/motoko/threshold-ecdsa
-dfx start --background
-```
-
-### Step 2: Deploy the canisters
-
-```bash
-dfx deploy
-```
-
-If successful, you should see something like this:
-
-```bash
-Deployed canisters.
-URLs:
-  Backend canister via Candid interface:
-    ecdsa_example_motoko: http://127.0.0.1:4943/?canisterId=t6rzw-2iaaa-aaaaa-aaama-cai&id=st75y-vaaaa-aaaaa-aaalq-cai
-```
-
-If you open the URL in a web browser, you will see a web UI that shows the public methods the canister exposes. Since the canister exposes `public_key` and `sign` methods, those are rendered in the web UI.
-
-## Deploying the canister on the mainnet
-
-To deploy this canister to the mainnet, one needs to do two things:
-
-- Acquire cycles (the equivalent of "gas" on other blockchains). This is necessary for all canisters.
-- Update the sample source code to have the right key ID. This is unique to this canister.
-
-### Acquire cycles to deploy
-
-Deploying to the Internet Computer requires [cycles](https://internetcomputer.org/docs/current/developer-docs/getting-started/tokens-and-cycles) (the equivalent of "gas" on other blockchains).
-
-### Update source code with the right key ID
-
-To deploy the sample code, the canister needs the right key ID for the right environment. Specifically, one needs to replace the value of the `key_id` in the `src/ecdsa_example_motoko/main.mo` file of the sample code. Before deploying to the mainnet, one should modify the code to use the right name of the `key_id`.
+To deploy the sample code from ICP Ninja, the canister needs the right key ID for the right environment. Specifically, one needs to replace the value of the `key_id` in the `src/ecdsa_example_motoko/main.mo` file of the sample code. Before deploying to the mainnet from ICP Ninja, one should modify the code to use the right name of the `key_id`.
 
 There are three options:
 
@@ -97,80 +51,24 @@ let { signature } = await ic.sign_with_ecdsa({
 > [!WARNING]
 > To deploy to IC mainnet, one needs to replace the value in `key_id` fields with the values `"dfx_test_key"` to instead have either `"test_key_1"` or `"key_1"` depending on the desired intent.
 
-### Deploying
-
-To [deploy via mainnet](https://internetcomputer.org/docs/current/developer-docs/setup/deploy-mainnet.md), run the following commands:
-
-```bash
-npm install
-dfx deploy --network ic
-```
-If successful, you should see something like this:
-
-```bash
-Deployed canisters.
-URLs:
-  Backend canister via Candid interface:
-    ecdsa_example_motoko: https://a3gq9-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=736w4-cyaaa-aaaal-qb3wq-cai
-```
 
-In the example above, `ecdsa_example_motoko` has the URL https://a3gq9-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=736w4-cyaaa-aaaal-qb3wq-cai and serves up the Candid web UI for this particular canister deployed on mainnet.
+## Build and deploy from the command-line
 
-## Obtaining public keys
+### 1. [Download and install the IC SDK.](https://internetcomputer.org/docs/building-apps/getting-started/install)
 
-### Using the Candid UI
+### 2. Download your project from ICP Ninja using the 'Download files' button on the upper left corner, or [clone the GitHub examples repository.](https://github.com/dfinity/examples/)
 
-If you deployed your canister locally or to the mainnet, you should have a URL to the Candid web UI where you can access the public methods. We can call the `public-key` method.
+### 3. Navigate into the project's directory.
 
-In the example below, the method returns `03c22bef676644dba524d4a24132ea8463221a55540a27fc86d690fda8e688e31a` as the public key.
+### 4. Deploy the project to your local environment:
 
-```json
-{
-  "Ok":
-  {
-    "public_key_hex": "03c22bef676644dba524d4a24132ea8463221a55540a27fc86d690fda8e688e31a"
-  }
-}
 ```
-
-
-### Code walkthrough
-Open the file `main.mo`, which will show the following Motoko code that demonstrates how to obtain an ECDSA public key.
-
-```motoko
-  //declare "ic" to be the management canister, which is evoked by `actor("aaaaa-aa")`. This is how we will obtain an ECDSA public key
-  let ic : IC = actor("aaaaa-aa");
-
-  public shared (msg) func public_key() : async { #Ok : { public_key: Blob }; #Err : Text } {
-    let caller = Principal.toBlob(msg.caller);
-
-    try {
-
-      //request the management canister to compute an ECDSA public key
-      let { public_key } = await ic.ecdsa_public_key({
-
-          //When `null`, it defaults to getting the public key of the canister that makes this call
-          canister_id = null;
-          derivation_path = [ caller ];
-          //this code uses the mainnet test key
-          key_id = { curve = #secp256k1; name = "test_key_1" };
-      });
-
-      #Ok({ public_key })
-
-    } catch (err) {
-
-      #Err(Error.message(err))
-
-    }
-
-  };
+dfx start --background --clean && dfx deploy
 ```
 
-In the code above, the canister calls the `ecdsa_public_key` method of the [IC management canister](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-management-canister) (`aaaaa-aa`).
-
+## Obtaining public keys
 
-**The [IC management canister](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-management-canister) is just a facade; it does not exist as a canister (with isolated state, Wasm code, etc.). It is an ergonomic way for canisters to call the system API of the IC (as if it were a single canister). In the code below, we use the management canister to create an ECDSA public key. `let ic : IC = actor("aaaaa-aa")` declares the IC management canister in the code above.**
+If you deployed your canister locally or to the mainnet, you should have a URL to the Candid web UI where you can access the public methods. We can call the `public-key` method.
 
 ### Canister root public key
 
@@ -185,24 +83,6 @@ For obtaining the canister's root public key, the derivation path in the API can
 
 Computing threshold ECDSA signatures is the core functionality of this feature. **Canisters do not hold ECDSA keys themselves**, but keys are derived from a master key held by dedicated subnets. A canister can request the computation of a signature through the management canister API. The request is then routed to a subnet holding the specified key and the subnet computes the requested signature using threshold cryptography. Thereby, it derives the canister root key or a key obtained through further derivation, as part of the signature protocol, from a shared secret and the requesting canister's principal identifier. Thus, a canister can only request signatures to be created for its canister root key or a key derived from it. This means that canisters "control" their private ECDSA keys in that they decide when signatures are to be created with them, but don't hold a private key themselves.
 
-```motoko
-  public shared (msg) func sign(message_hash: Blob) : async { #Ok : { signature: Blob };  #Err : Text } {
-    assert(message_hash.size() == 32);
-    let caller = Principal.toBlob(msg.caller);
-    try {
-      Cycles.add(10_000_000_000);
-      let { signature } = await ic.sign_with_ecdsa({
-          message_hash;
-          derivation_path = [ caller ];
-          key_id = { curve = #secp256k1; name = "dfx_test_key" };
-      });
-      #Ok({ signature })
-    } catch (err) {
-      #Err(Error.message(err))
-    }
-  };
-```
-
 ## Signature verification
 
 For completeness of the example, we show that the created signatures can be verified with the public key corresponding to the same canister and derivation path.
@@ -223,10 +103,6 @@ The call to `ecdsaVerify` function should always return `true`.
 
 Similar verifications can be done in many other languages with the help of cryptographic libraries that support the `secp256k1` curve.
 
-## Conclusion
-
-In this walkthrough, we deployed a sample smart contract that:
+## Security considerations and best practices
 
-* Signed with private ECDSA keys even though **canisters do not hold ECDSA keys themselves**.
-* Requested a public key.
-* Performed signature verification.
+If you base your application on this example, it is recommended that you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/building-apps/security/overview) for developing on ICP. This example may not implement all the best practices.
