DEV Community

Bastien Faivre
Bastien Faivre

Posted on • Edited on

A guide on Starknet signatures

#blockchain #typescript #go #tutorial

CHANGELOG

  • 25.12.2024: Updated Go code due to breaking changes in the starknet.go library (>= v0.7.3)
  • 28.12.2024: Updated article to work with any wallet type.

Abstract

This article outlines the process of signing and verifying a signature on Starknet. It begins by introducing Account Abstraction and how it modifies signature verification compared to traditional blockchains like Ethereum. It then provides comprehensive code examples in TypeScript and Go for signing a message and verifying a signature using two methods available on Starknet: using the user's public key and using the user's account address.

A live signature playground is available at https://signatures.felts.xyz

All the code examples given in this article are available in the associated GitHub repository. I want to thank Thiago for his help on the code snippets.

Account Abstraction

In Ethereum, individual user accounts, known as Externally Owned Accounts (EOAs), are controlled by a pair of private and public keys. Transactions require a signature from the private key to modify the account state. While secure, this system has significant drawbacks, such as irreversible asset loss if the private key is lost or stolen, limited wallet functionality, and a lack of user-friendly key or account recovery options.

Starknet addresses these limitations through Account Abstraction (AA), which manages accounts through smart contracts instead of private keys. This approach allows smart contracts to validate their transactions, enabling features like gas fees covered by smart contracts, multiple signers for a single account, and various cryptographic signatures. AA enhances security and user experience by enabling developers to design custom security models, such as different keys for routine and high-value transactions and biometric authentication for enhanced security. It also simplifies key recovery and management with methods like social recovery and hardware-based transaction signing. Additionally, AA supports key rotation, session keys for web3 applications, and diverse signature and validation schemes, allowing for tailored security measures. By addressing the inherent limitations of Ethereum's EOA model, Starknet's AA provides a more flexible, secure, and user-friendly approach to account management, significantly improving blockchain interactions.

Signature

With an understanding of Account Abstraction, we can now explore how it changes signature verification. First, it is essential to understand the composition of a signature. The STARK curve is an elliptic curve, and its signatures are ECDSA signatures, which consist of two values: r and s. The signature is generated by signing a message with the private key and can be verified using the public key. For more information about ECDSA signatures, refer to the Wikipedia page.

Signing a Message

In Starknet, messages to be signed typically follow the EIP-712 format. This message format includes four mandatory fields: types, primaryType, domain, and message. The types field maps type names to their corresponding type definitions. The primaryType field specifies the primary type of the message. The domain field contains key-value pairs that specify the chain context. The message field includes key-value pairs that describe the message. We usually represent the message as a JSON object:

{
    types: {
        StarkNetDomain: [
            { name: "name", type: "felt" },
            { name: "chainId", type: "felt" },
            { name: "version", type: "felt" },
        ],
        Message: [{ name: "message", type: "felt" }],
    },
    primaryType: "Message",
    domain: {
        name: "MyDapp",
        chainId: "SN_MAIN",
        version: "0.0.1",
    },
    message: {
        message: "hello world!",
    },
}
Enter fullscreen mode Exit fullscreen mode

To sign a message, you need the private key. For an in-depth understanding of the signature process, refer to the ECDSA signature algorithm. Below is the code to sign a message.

TypeScript:

import { ec, encode, TypedData, Signer, typedData, WeierstrassSignatureType } from 'starknet';

//--------------------------------------------------------------------------
// Account
//--------------------------------------------------------------------------
const privateKey = '0x1234567890987654321';

const starknetPublicKey = ec.starkCurve.getStarkKey(privateKey);

const fullPublicKey = encode.addHexPrefix(
    encode.buf2hex(ec.starkCurve.getPublicKey(privateKey, false))
);

const pubX = starknetPublicKey
const pubY = encode.addHexPrefix(fullPublicKey.slice(68))

//--------------------------------------------------------------------------
// Message
//--------------------------------------------------------------------------

const messageStructure: TypedData = {
    types: {
        StarkNetDomain: [
            { name: "name", type: "felt" },
            { name: "chainId", type: "felt" },
            { name: "version", type: "felt" },
        ],
        Message: [{ name: "message", type: "felt" }],
    },
    primaryType: "Message",
    domain: {
        name: "MyDapp",
        chainId: "SN_MAIN",
        version: "0.0.1",
    },
    message: {
        message: "hello world!",
    },
};

const messageHash = typedData.getMessageHash(messageStructure, BigInt(starknetPublicKey))

//--------------------------------------------------------------------------
// Signature
//--------------------------------------------------------------------------

const signer = new Signer(privateKey)

let signature: WeierstrassSignatureType;
try {
    signature = (await signer.signMessage(messageStructure, starknetPublicKey)) as WeierstrassSignatureType
} catch (error) {
    console.error("Error signing the message:", error);
}

// signature has properties r and s
Enter fullscreen mode Exit fullscreen mode

Go:

package main

import (
    "fmt"
    "math/big"
    "strconv"

    "github.com/NethermindEth/starknet.go/curve"
    "github.com/NethermindEth/starknet.go/typedData"
    "github.com/NethermindEth/starknet.go/utils"
)

const typedDataContent = `
{
    "types": {
        "StarkNetDomain": [
            { "name": "name", "type": "felt" },
            { "name": "chainId", "type": "felt" },
            { "name": "version", "type": "felt" }
        ],
        "Message": [
            { "name": "message", "type": "felt" }
        ]
    },
    "primaryType": "Message",
    "domain": {
        "name": "MyDapp",
        "chainId": "SN_MAIN",
        "version": "0.0.1"
    },
    "message": {
        "message": "hello world!"
    }
}
`

func main() {
    //--------------------------------------------------------------------------
    // Account with public key
    //--------------------------------------------------------------------------
    privateKey, _ := new(big.Int).SetString("1234567890987654321", 16)

    pubX, pubY, err := curve.Curve.PrivateToPoint(privateKey)
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }
    if !curve.Curve.IsOnCurve(pubX, pubY) {
        fmt.Printf("Point is not on curve\n")
        return
    }

    starknetPublicKey := pubX

    // IMPORTANT: this is not a standard way to retrieve the full public key, it
    // is just for demonstration purposes as starknet.go does not provide a way
    // to retrieve the full public key at the time of writing.
    // Rule of thumb: never write your own cryptography code!
    fullPublicKey := new(big.Int).SetBytes(append(append(
        []byte{0x04},                       // 0x04 is the prefix for uncompressed public keys
        pubX.Bytes()...), pubY.Bytes()...), // concatenate x and y coordinates
    )

    fmt.Println("Account:")
    fmt.Printf("\tPrivate key: 0x%s\n", privateKey.Text(16))
    // 0x1234567890987654321
    fmt.Printf("\tFull (uncompressed) public key: 0x%s\n", fullPublicKey.Text(16))
    // 0x4020c29f1c98f3320d56f01c13372c923123c35828bce54f2153aa1cfe61c44f2018277bc1bc80570f859cb882ca70d52f1a0e06275e5dd704dddbbe19faadf
    fmt.Printf("\tCoordinates of the public key: x=0x%s, y=0x%s\n", pubX.Text(16), pubY.Text(16))
    // x=0x20c29f1c98f3320d56f01c13372c923123c35828bce54f2153aa1cfe61c44f2, y=0x18277bc1bc80570f859cb882ca70d52f1a0e06275e5dd704dddbbe19faadf
    fmt.Printf("\tStarknet public key: 0x%s (= x-coordinate of the public key)\n", starknetPublicKey.Text(16))
    // 0x20c29f1c98f3320d56f01c13372c923123c35828bce54f2153aa1cfe61c44f2

    //--------------------------------------------------------------------------
    // Message with public key
    //--------------------------------------------------------------------------

    // NOTE: one can also build the typed data manually, following the fields
    // and types defined in typedData.TypedData struct.
    var ttd typedData.TypedData
    err = json.Unmarshal([]byte(typedDataContent), &ttd)
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }

    hash, err := ttd.GetMessageHash(starknetPublicKey.String())
    if err != nil {
        fmt.Printf("Error: %s\n", err)
        return
    }

    fmt.Println("\nMessage:")
    fmt.Printf("\tMessage hash: 0x%s\n", hash.Text(16))
    // 0x197093614bca282524e6b8f77de8f7dd9a9dd92ed4ea7f4f2b17f95e2bc441d

    //--------------------------------------------------------------------------
    // Signature and verification with public key (check locally on curve)
    //--------------------------------------------------------------------------

    r, s, err := curve.Curve.Sign(hash.BigInt(new(big.Int)), privateKey)
    if err != nil {
        fmt.Println("Error signing message:", err)
        return
    }
}
Enter fullscreen mode Exit fullscreen mode

If you are developing a dApp, you won't have access to the user's private key. Instead, you can use the starknet.js library to sign the message. The code will interact with the browser wallet (typically ArgentX or Braavos) to sign the message. You can find a live demo at https://signatures.felts.xyz. Here is the simplified code to sign a message in TypeScript using the browser wallet (full code available in the GitHub repository):

import { connect } from "get-starknet";

const starknet = await connect(); // Connect to the browser wallet

const messageStructure: TypedData = {
    types: {
        StarkNetDomain: [
            { name: "name", type: "felt" },
            { name: "chainId", type: "felt" },
            { name: "version", type: "felt" },
        ],
        Message: [{ name: "message", type: "felt" }],
    },
    primaryType: "Message",
    domain: {
        name: "MyDapp",
        chainId: "SN_MAIN",
        version: "0.0.1",
    },
    message: {
        message: "hello world!",
    },
};

// skipDeploy allows not-deployed accounts to sign messages
const signature = await starknet.account.signMessage(messageStructure, { skipDeploy: true });
Enter fullscreen mode Exit fullscreen mode

The obtained signature is an array of strings. It is important to notice that each wallet will have its unique signature format (use the signatures playground to convince yourself). But, this is not important because we do not have to interact with the content of the signature (aka the string array). Indeed, please continue reading to the signature verification section to learn how is this string array used.

However, most signature formats will include an ECDSA signature in the form of two values: r and s. Note that some wallets might do multiple ECDSA signatures!

Verifying a Signature

To verify a signature, the public key is required from a cryptographic perspective. However, due to Account Abstraction in Starknet, access to the public key is not always available. Currently, the public key cannot be retrieved through the browser wallet. Therefore, two methods are distinguished for verifying a signature: using the user's public key (if available) or using the user's address (i.e., account smart contract address).

Using the User's Public Key

If the user's public key is available, the signature can be verified using the public key. Here is the code to verify a signature.

TypeScript:

// following the previous code
const isValid = ec.starkCurve.verify(signature, messageHash, fullPublicKey)
Enter fullscreen mode Exit fullscreen mode

Go:

// following the previous code
isValid := curve.Curve.Verify(hash.BigInt(new(big.Int)), r, s, starknetPublicKey, pubY)
Enter fullscreen mode Exit fullscreen mode

Using the User's Address

NOTE: This method works only if the user's account smart contract has been deployed (activated) on the Starknet network. This deployment is typically done through the browser wallet when the user creates an account and requires some gas fees. The skipDeploy parameter is specified in the JavaScript code when signing with the browser wallet. The example code provided earlier will not work with signatures different from the browser wallet since a sample private key was used to sign the message.

IMPORTANT: Avoid using your own private key when experimenting with the code. Always sign transactions with the browser wallet.

If the user's public key is unavailable, the signature can be verified using the user's account smart contract. By the standard SRC-6, the user account smart contract has a function fn is_valid_signature(hash: felt252, signature: Array<felt252>) -> felt252; that takes the hash of the message and the signature (in the form of a string array) and returns the string VALID if the signature is valid, or fails otherwise. Here is the code to verify a signature using the user's account address in TypeScript and Go.

TypeScript (simplified for readability):

import { Account, RpcProvider } from "starknet";

const provider = new RpcProvider({ nodeUrl: "https://your-rpc-provider-url" });

// '0x123' is a placeholder for the user's private key since we don't have access to it
const account = new Account(provider, address, '0x123')

try {
    // messageStructure and signature are obtained from the previous code when signing the message with the browser wallet
    const isValid = account.verifyMessage(messageStructure, signature)
    console.log("Signature is valid:", isValid)
} catch (error) {
    console.error("Error verifying the signature:", error);
}
Enter fullscreen mode Exit fullscreen mode

Go (simplified for readability):

import (
    "context"
    "encoding/hex"
    "fmt"
    "math/big"

    "github.com/NethermindEth/juno/core/felt"
    "github.com/NethermindEth/starknet.go/curve"
    "github.com/NethermindEth/starknet.go/rpc"
    "github.com/NethermindEth/starknet.go/utils"
)

...

provider, err := rpc.NewProvider("https://your-rpc-provider-url")
if err != nil {
    // handle error
}

// we import the account address and the signature from the frontend (typescript)
accountAddressInFelt, _ := utils.HexToFelt("0xabc123")
signature := []string{"0xabc123", "0x123abc"}

// we need to get the message hash, but, this time, we use the account address instead of the public key. `tdd` is the same as the in the previous Go code
hash, err := ttd.GetMessageHash("0xabc123") // account address
if err != nil {
    // handle error
}

callData := []*felt.Felt{
    hash,
    (&felt.Felt{}).SetUint64(uint64(len(signature))), // size of the string array
}

for _, value := range signature {
    callData = append(
        callData,
        utils.HexToFelt(value),
    )
}

tx := rpc.FunctionCall{
    ContractAddress: accountAddressInFelt,
    EntryPointSelector: utils.GetSelectorFromNameFelt(
        "is_valid_signature",
    ),
    Calldata: callData,
}

result, err := provider.Call(context.Background(), tx, rpc.BlockID{Tag: "latest"})
if err != nil {
    // handle error
}

resultHex := result[0].Text(16)

isValid, err := hex.DecodeString(resultHex)
if err != nil && resultHex != "1" {
    // handle error
}

fmt.Println("Signature is valid:", string(isValid) == "VALID" || resultHex == "1")
Enter fullscreen mode Exit fullscreen mode

Usage

Signatures can be used in various applications, with user authentication in web3 dApps being a primary use case. To achieve this, use the structure provided above for signature verification using the user's account address. Here is the complete workflow:

  1. The user signs a message with the browser wallet.
  2. Send the user address, message, and signature (string array) to the backend.
  3. The backend verifies the signature using the user's account smart contract.

Make sure that the message structure is the same on the frontend and backend to ensure the signature is verified correctly.

Conclusion

I hope that this article provided you with a comprehensive understanding of the signatures on Starknet and helped you implement it in your applications. If you have any questions or feedback, feel free to comment or reach out to me on Twitter or GitHub. Thank you for reading!

Sources:

Top comments (0)

Read next

msnmongare profile image

How to Set Git Username and Password in Git Bash?

Sospeter Mong'are -

anticoder03 profile image

"Day 7 with GSAP: Interactive Scrolling Animation with Rotating Arrows"

Ashish prajapati -

leandroveiga profile image

Building AI and Machine Learning Applications with .NET 9: A Comprehensive Guide

Leandro Veiga -

arbythecoder profile image

Day 33: Deploying a Three-Tier App on Kubernetes: A Simple Guide

Arbythecoder -