---

The Complete Guide to Cairo's Secret Handshake: Mastering Bitwise Operations from Zero to Hero

Learn to solve the Cairo Secret Handshake challenge by converting a number to a sequence of actions using bitwise operations. This guide covers binary logic, array manipulation, and conditional reversing, providing a deep dive into Cairo's powerful features for low-level data handling and smart contract optimization.

---

Imagine you're part of an exclusive club, a digital speakeasy where entry isn't granted by a password, but by a secret, coded sequence of actions. You whisper a number, and your counterpart responds with a specific series of gestures. This isn't a scene from a spy movie; it's a perfect analogy for one of the most fundamental concepts in programming: bitwise operations. Many developers, especially those new to systems-level languages like Cairo, find bit manipulation intimidating, a cryptic world of 1s and 0s. You might feel that it's too complex or disconnected from practical application.

This feeling is completely valid. But what if I told you that mastering this "secret handshake" is the key to unlocking a new level of efficiency and control in your Cairo smart contracts? This guide promises to demystify bitwise logic completely. We will break down the Secret Handshake problem from the exclusive kodikra.com learning path, transforming abstract binary theory into a tangible, powerful tool you can use to write more optimized, gas-efficient, and elegant code on Starknet.

What is the Secret Handshake Challenge?

At its core, the Secret Handshake challenge is a logic puzzle designed to test your understanding of binary representation and bit manipulation. The premise is simple: you are given a number (specifically, a u8 integer between 1 and 31), and your task is to translate this number into a specific sequence of actions.

The translation isn't arbitrary. It's determined by the binary representation of the input number. We only care about the first five bits (from right to left), as these are enough to represent any number up to 31 (since 2^5 = 32). Each of these five bits corresponds to a unique action or a command modifier.

The Rules of Engagement

The logic follows a precise set of rules mapped to the binary digits of the input number. When you convert a number like 19 to binary, you get 10011. The handshake protocol reads these bits from right to left (from least significant to most significant).

Here is the mapping between the bit's position (and its decimal value) and the corresponding action:

Binary Representation	Decimal Value	Action	Description
...00001	1	wink	The rightmost bit (bit 0).
...00010	2	double blink	The second bit from the right (bit 1).
...00100	4	close your eyes	The third bit from the right (bit 2).
...01000	8	jump	The fourth bit from the right (bit 3).
...10000	16	Reverse	The fifth bit from the right (bit 4). This is a modifier, not an action.

For example, if the input number is 9, its binary form is 01001. Reading from right to left:

• The first bit (value 1) is ON. This means we add "wink" to our sequence.
• The second, third bits are OFF.
• The fourth bit (value 8) is ON. We add "jump" to our sequence.
• The fifth bit is OFF, so no reversal is needed.

The final sequence for the number 9 is ["wink", "jump"].

If the input number is 19, its binary form is 10011. Reading from right to left:

• Bit 0 (value 1) is ON: "wink".
• Bit 1 (value 2) is ON: "double blink".
• Bits 2 and 3 are OFF.
• Bit 4 (value 16) is ON: This is the reverse flag!

The initial sequence is ["wink", "double blink"]. Because the reverse flag is set, we must reverse this sequence, resulting in the final output: ["double blink", "wink"].

---

Why This Challenge is Crucial for Cairo Developers

While the Secret Handshake might seem like a whimsical puzzle, the underlying principles are fundamental to writing high-performance and cost-effective smart contracts in Cairo. The Starknet ecosystem, like other blockchains, places a high premium on computational and storage efficiency. Every operation and every byte of stored data costs gas, and mastering bitwise operations is a direct path to minimizing these costs.

Gas Optimization and State Packing

On-chain storage is one of the most expensive resources. Imagine you need to store multiple boolean flags for a user's status: is_active, is_verified, has_voted, is_admin. Storing each of these in a separate boolean slot is incredibly inefficient. Instead, a savvy Cairo developer can "pack" these flags into a single integer (like a u8 or u32). Each bit within that integer can represent one of the boolean flags. The Secret Handshake logic—checking if a specific bit is "on"—is precisely how you would read or update these packed flags, saving significant storage costs.

Handling Permissions and Roles

Bitmasks are a common and powerful pattern for managing permissions. Instead of assigning a user a simple role like "editor," you can grant them a combination of fine-grained permissions. For example:

• READ = 1 (binary 001)
• WRITE = 2 (binary 010)
• DELETE = 4 (binary 100)

A user with READ and WRITE permissions would have their permission value set to 3 (binary 011). To check if they can write, your contract would simply perform a bitwise AND: if (user_permissions & WRITE) != 0. This is a highly efficient way to implement complex, layered access control systems in smart contracts.

Interacting with Low-Level Data

Cairo is designed to be a provable computation language, which often involves working closer to the "metal" than typical high-level languages. Understanding how data is represented in binary is essential for tasks like parsing data from external calls, optimizing cryptographic computations, or building custom data structures that are compact and efficient. The skills honed in this challenge are directly transferable to these advanced use cases.

---

How The Logic Works: A Deep Dive into the Algorithm

To solve the Secret Handshake, we need a systematic way to check each of the five relevant bits of the input number. The most effective tool for this job is the bitwise AND operator (&). Let's break down the entire process from start to finish.

Step 1: The Foundation - Understanding Bitwise AND (&)

The bitwise AND operator compares two numbers on a bit-by-bit basis. For each corresponding pair of bits, the result is 1 only if both bits are 1. Otherwise, the result is 0.

For example, let's AND the numbers 9 (01001) and 17 (10001):

  01001  (Decimal 9)
& 10001  (Decimal 17)
-------
  00001  (Decimal 1)

This property is perfect for checking if a specific bit is set. We can create a "mask," which is a number that has only one bit set to 1—the very bit we want to inspect. If we AND our input number with this mask, the result will be non-zero if and only if the corresponding bit in our input number was also 1.

For instance, to check if the "wink" bit (the first bit, value 1) is set in the number 9 (01001):

  01001  (Input number 9)
& 00001  (Mask for "wink")
-------
  00001  (Result is 1, which is non-zero)

Since the result is not zero, we know the "wink" bit is set. This is the core mechanic of our solution.

Step 2: The Algorithm Flow for a Single Action

For each potential action ("wink", "double blink", etc.), we follow a simple decision-making process. This can be visualized as a small flowchart.

    ● Start with Input Number (e.g., 9) & Action Mask (e.g., 1 for 'wink')
    │
    ▼
  ┌───────────────────────────┐
  │ Perform Bitwise AND       │
  │ `input_number & mask`     │
  └─────────────┬─────────────┘
                │
                ▼
      ◆ Result is non-zero?
     ╱                         ╲
    Yes                         No
    │                           │
    ▼                           ▼
┌──────────────────┐      ┌───────────────────┐
│ Add action       │      │ Do nothing, move  │
│ to the sequence  │      │ to the next bit   │
└──────────────────┘      └───────────────────┘

Step 3: The Complete Algorithm - From Number to Handshake

Now, we can assemble these steps into a complete algorithm that handles all five bits and produces the final, correctly ordered sequence of actions.

1. Initialization: Create an empty, mutable array that will store the sequence of handshake actions (as ByteArray strings).
2. Action Checks (Bits 0-3): Iterate through the first four actions. For each action, create the corresponding bitmask (1, 2, 4, 8). Use the bitwise AND operation to check if the bit is set in the input number. If it is, append the action's string to your array.
3. Reverse Check (Bit 4): After checking the first four bits, check the fifth bit using the mask for 16. This bit determines the final order of the actions.
4. Conditional Reversal: If the fifth bit was set, reverse the array of actions you have built. If it was not set, do nothing and leave the array as is.
5. Return: Return the final array of actions.

This process is deterministic and correctly translates any number from 1 to 31 into its corresponding secret handshake. Here is a visualization of the full logic flow:

    ● Input: `number: u8`
    │
    ▼
  ┌─────────────────────────────┐
  │ Initialize `actions: Array` │
  └──────────────┬──────────────┘
                 │
                 ▼
    ◆ (number & 1) != 0 ? ──────── Yes ⟶ Append "wink"
                 │
                 No
                 │
                 ▼
    ◆ (number & 2) != 0 ? ──────── Yes ⟶ Append "double blink"
                 │
                 No
                 │
                 ▼
    ◆ (number & 4) != 0 ? ──────── Yes ⟶ Append "close your eyes"
                 │
                 No
                 │
                 ▼
    ◆ (number & 8) != 0 ? ──────── Yes ⟶ Append "jump"
                 │
                 No
                 │
                 ▼
  ┌─────────────────────────────┐
  │ Actions array is now built  │
  └──────────────┬──────────────┘
                 │
                 ▼
    ◆ (number & 16) != 0 ?
     ╱                         ╲
    Yes                         No
    │                           │
    ▼                           │
┌──────────────┐                │
│ Reverse the  │                │
│ actions array│                │
└──────────────┘                │
    ╲                           │
     ╲                          │
      └───────────┬─────────────┘
                  ▼
    ● Output: Final `actions: Array`

---

Cairo Code Walkthrough and Optimization

Now let's translate our algorithm into functional Cairo code. We will first analyze a straightforward implementation from the kodikra learning module and then discuss key optimizations to make it more efficient and idiomatic.

Initial Solution Code

Here is a valid solution that correctly implements the logic we've discussed. It uses a loop and the pow() function to generate the bitmasks.

use core::num::traits::Pow;

// Helper function to provide the action strings
fn actions() -> Array<ByteArray> {
    array
![
        "wink",
        "double blink",
        "close your eyes",
        "jump"
    ]
}

pub fn commands(number: u8)
 -> Array<ByteArray> {
    let mut results: Array<ByteArray> = array
![];
    let mut i: u32 = 0;
    let action_list = actions()
;

    // Loop through the first 4 actions
    loop {
        if i >= 4 {
            break;
        }

        // Check if the i-th bit is set using 2^i as the mask
        if number.into() & 2_u32.pow(i) != 0 {
            results.append(*action_list.get(i.into()).unwrap());
        }
        i += 1;
    };

    // Check for the reverse flag (bit 4, value 16)
    if number & 16 != 0 {
        // Manual reversal of the array
        let mut reversed: Array<ByteArray> = array
![];
        let mut j = results.len()
;
        while j > 0 {
            j -= 1;
            reversed.append(*results.get(j).unwrap());
        }
        return reversed;
    } else {
        return results;
    }
}

Line-by-Line Code Explanation

Let's dissect this implementation to understand exactly what's happening.

• use core::num::traits::Pow;: This line imports the Pow trait, which allows us to calculate powers of numbers, like 2.pow(i). This is used to generate the bitmasks 1, 2, 4, and 8 dynamically.
• fn actions() -> Array<ByteArray>: A simple helper function that returns a fixed array of the possible action strings. This keeps the main logic clean.
• pub fn commands(number: u8) -> Array<ByteArray>: This is our main function. It takes a u8 integer and is expected to return an Array of ByteArrays (strings).
• let mut results: Array<ByteArray> = array ![];: We initialize an empty, mutable array named results to store the determined actions.
• loop { ... }: This loop iterates from i = 0 to 3.
• if number.into() & 2_u32.pow(i) != 0: This is the core logic.
  • number.into(): Converts the u8 number to a type compatible with the right side (a u32 from pow).
  • 2_u32.pow(i): Calculates the bitmask. For i=0, this is 2^0=1. For i=1, this is 2^1=2, and so on.
  • &: The bitwise AND operator checks if the bit is set.
  • != 0: The condition is true if the bit was set.
• results.append(...): If the condition is true, the corresponding action string is fetched from action_list and appended to our results array.
• if number & 16 != 0: After the loop, this condition checks for the reverse flag (the fifth bit, which has a decimal value of 16).
• Manual Reversal Block: If the reverse flag is set, a new empty array reversed is created. A while loop then iterates through the results array from back to front, appending each element to reversed. This effectively creates a reversed copy, which is then returned.
• else { return results; }: If the reverse flag is not set, the original results array is returned as is.

Code Optimization: From Good to Great

The initial solution works, but it's not as efficient or idiomatic as it could be. In a gas-sensitive environment like Starknet, every optimization matters. Let's improve it.

Optimization 1: Replace pow() with Bit-Shifting

Calculating powers (pow()) is a computationally more expensive operation than bit-shifting. The left bit-shift operator (<<) is the natural and highly efficient way to create bitmasks. The expression 1 << i is equivalent to 2.pow(i) but is significantly faster.

• 1 << 0 results in 1 (binary 00001)
• 1 << 1 results in 2 (binary 00010)
• 1 << 2 results in 4 (binary 00100)
• And so on...

Optimization 2: Use Built-in Array Reversal

The manual reversal loop is verbose and unnecessary. The Cairo core library provides a built-in reverse() method for arrays which is more readable, less error-prone, and likely more optimized under the hood.

Optimization 3: Simplify the Logic with Hardcoded Masks

Since we are only checking 4-5 specific bits, a loop might be overkill. A more direct approach with hardcoded masks can be clearer and avoids the overhead of a loop structure. This is a stylistic choice, but it often leads to more readable code for a fixed number of checks.

The Optimized and Refactored Solution

Here is the improved version of the code that incorporates these optimizations.

pub fn commands(number: u8) -> Array<ByteArray> {
    let mut results: Array<ByteArray> = array
![];

    // Use direct bitwise checks with efficient hardcoded masks.
    // This is often clearer and faster than a loop for a small, fixed set.
    if (number & 1)
 != 0 { // Bit 0: 'wink'
        results.append("wink");
    }
    if (number & 2) != 0 { // Bit 1: 'double blink'
        results.append("double blink");
    }
    if (number & 4) != 0 { // Bit 2: 'close your eyes'
        results.append("close your eyes");
    }
    if (number & 8) != 0 { // Bit 3: 'jump'
        results.append("jump");
    }

    // Check for the reverse flag (bit 4).
    if (number & 16) != 0 {
        // Use the efficient, built-in reverse method.
        results.reverse();
    }

    results
}

This version is superior for several reasons:

• Readability: The intent of each if statement is immediately clear. `if (number & 1) != 0` is more self-documenting than `if number & 2.pow(i) != 0` inside a loop.
• Performance: It avoids the overhead of the pow() function and loop setup. The built-in reverse() is highly optimized.
• Conciseness: The code is shorter, cleaner, and has less cognitive overhead for the next developer who reads it.

---

Where This Pattern is Used in Real-World Cairo/Starknet

The principles of the Secret Handshake challenge are not just theoretical. They are actively used in production-grade smart contracts on Starknet for optimization and feature implementation.

Use Case 1: NFT Trait Encoding

Imagine an NFT project where each token can have multiple boolean traits: "Has Hat," "Has Glasses," "Is Shiny," "Is Rare." Instead of storing four separate boolean values in the contract's storage, you can pack them into a single u8. A token with a trait value of 5 (binary 0101) would mean it "Has Hat" (bit 0) and "Is Shiny" (bit 2). Your contract's metadata function would use bitwise ANDs to decode this integer and report the correct traits.

Use Case 2: DeFi Protocol Feature Flags

A decentralized finance (DeFi) protocol might have several features that can be toggled on or off by governance, such as "Flash Loans Enabled," "Staking Rewards Active," or "Trading Paused." A single configuration variable, an integer, can hold all these flags. A governance proposal would simply update this single storage slot with a new integer value, and all functions within the protocol would check the relevant bits before executing.

// Example of checking a feature flag
const TRADING_PAUSED_FLAG: u32 = 4; // 0b100

fn execute_trade(...) {
    let config_flags = get_protocol_config();
    assert((config_flags & TRADING_PAUSED_FLAG) == 0, 'Trading is currently paused');
    // ... rest of the trade logic
}

Pros and Cons of Using Bitmasks

While powerful, this technique has trade-offs. It's important to know when to use it.

Aspect	Using Bitmasks (e.g., a single u8)	Using Structs or Multiple Variables
Gas Cost (Storage)	Extremely low. Multiple flags fit into a single storage slot.	High. Each boolean or variable occupies its own storage slot.
Gas Cost (Computation)	Very low. Bitwise operations are among the cheapest CPU instructions.	Low. Reading individual variables is also cheap.
Readability	Lower. Requires understanding bitwise logic. Code like if (flags & 8) is less intuitive than if user.can_jump.	High. The code is self-explanatory and easy for new developers to understand.
Extensibility	Limited. You are constrained by the number of bits in your integer type (e.g., 8 flags for a u8). Adding a 9th flag requires changing the data type.	High. Adding a new field to a struct is straightforward.

Verdict: Use bitmasks when you have a set of related boolean flags, and storage or computation cost is a primary concern. For unrelated, high-level business logic where clarity is paramount, a struct may be the better choice.

---

Frequently Asked Questions (FAQ)

Why is the input number in this problem limited to 1-31?

The problem is designed around 5 bits. With 5 bits, you can represent 2⁵ = 32 unique values, which correspond to the numbers 0 through 31. Since the problem specifies numbers *between* 1 and 31, it fits perfectly within this 5-bit constraint.

What exactly is a bitwise AND (&) operator?

It's a binary operator that takes two numbers and performs a logical AND operation on each pair of corresponding bits. The resulting bit is 1 only if both of the input bits at that position are 1. It's primarily used for "masking," which allows you to check or extract specific bits from a number.

Why is bit-shifting (<<) considered better than using a pow() function for this task?

Bit-shifting is a fundamental, low-level CPU instruction, making it exceptionally fast. A pow() function, especially for integer powers, often involves more complex calculations or loops. For creating powers of 2 (which is what bitmasks are), bit-shifting is the most direct, readable, and performant method available in languages like Cairo.

Could I use a match statement instead of multiple if conditions?

A match statement is typically used to branch based on the entire value of a variable. It's not well-suited for checking individual, non-exclusive bits. For example, the number 3 (00011) needs to trigger actions for both 1 and 2. A match statement can't easily handle this combinatorial logic, making separate if statements the far more appropriate tool for this problem.

How does this concept of bit manipulation apply to the felt252 type in Cairo?

While felt252 is a field element and not a standard unsigned integer, the same bitwise principles apply. You can perform bitwise operations on felt252 values. This is extremely useful for packing large amounts of data, as a single felt252 can hold up to 252 bits of information, allowing for massive storage savings in complex smart contracts.

What are the other common bitwise operators in Cairo?

Besides AND (&), Cairo supports other standard bitwise operators:

• OR (|): Sets a bit to 1 if either of the input bits is 1. Used to turn bits ON.
• XOR (^): Sets a bit to 1 if the input bits are different. Used to toggle bits.
• NOT (!): Inverts all the bits of a number. (Note: In Cairo, this is often handled in context of the type).
• Left Shift (<<) and Right Shift (>>): Move all bits to the left or right.

Where can I learn more about low-level operations and Cairo optimization?

This Secret Handshake module is just one part of a comprehensive curriculum. To deepen your understanding of Cairo's powerful features, from basic syntax to advanced optimization techniques, explore our complete Cairo language guide available exclusively at kodikra.com.

---

Conclusion: The Handshake Unlocked

The Secret Handshake is more than just a coding puzzle; it's a gateway to understanding the heart of computational efficiency. By working through this challenge, you've moved beyond simply writing code that works to writing code that performs. You have unlocked a fundamental skill set that separates proficient developers from exceptional ones, especially in the resource-constrained world of blockchain.

You now understand not only the "how" of implementing the logic but also the critical "why" behind its importance—from saving gas on Starknet with state packing to building robust permission systems. The optimized Cairo code we developed is a testament to the elegance and power that comes from mastering low-level operations.

Technology Disclaimer: The code and concepts discussed in this article are based on Cairo 1.0 and later versions. The Cairo language and its ecosystem are continuously evolving. Always refer to the official Starknet and Cairo documentation for the latest syntax and best practices.

Ready to tackle the next challenge? Continue your journey to becoming a top-tier Cairo developer by exploring the full Cairo Learning Path on kodikra.com. Dive deeper, build smarter, and master the art of provable computation.

---

Published by Kodikra — Your trusted Cairo learning resource.