DEV Community: Bastien Faivre

A Starknet transactions batcher

Bastien Faivre — Sun, 22 Dec 2024 17:55:36 +0000

CHANGELOG

16.01.2026: Updated Go code due to breaking changes in the starknet.go library (>= v0.17.1)
25.12.2024: Updated Go code due to breaking changes in the starknet.go library (>= v0.7.3)

Abstract

This article presents the transactions batcher used in Metacube to send NFTs earned by players instantly. It explains the batcher's scalable actor-based architecture and provides a detailed implementation in Go.

All the code snippets are available in the associated GitHub repository.

Architecture

The Batcher is composed of two main actors:

The Builder receives the transactions, batches them into a single multicall transaction, and sends it to the Sender actor.
The Sender finalizes the transaction with appropriate fields (nonce, max fee, etc.), signs it, sends it to the Starknet network, and monitors its status.

This actor separation allows for a scalable and efficient batcher. The builder prepares the transactions while the sender sends them, allowing for a continuous and efficient flow of transactions.

Implementation

The following implementation is specific to Go, but the concepts can easily be adapted to other languages, as the functionalities remain the same.

Moreover, note that this implementation is specific to sending NFTs from the same contract. However, a more generic approach is mentioned later in the article.

Lastly, the code is based on the starknet.go library developed by Nethermind.

Batcher

Let's start with the Batcher itself:

type Batcher struct {
    accnt           *account.Account
    contractAddress *felt.Felt
    maxSize         int
    inChan          <-chan []string
    failChan        chan<- []string
}

The account (accnt) is the one holding the NFTs, it will be used to sign the transactions that transfer them. These NFTs are part of the same contract, hence the contractAddress field. The maxSize field is the maximum size of a batch, and inChan is the channel where the transactions are sent to the Batcher. The failChan is used to send back the transactions that failed to be sent.

Note that, in this implementation, the later-called transaction data ([]string) is an array of two elements: the recipient address and the NFT ID.

The Batcher runs both the Builder and the Sender actors concurrently:

type TxnDataPair struct {
    Txn  rpc.InvokeTxnV1
    Data [][]string
}

func (b *Batcher) Run() {
    txnDataPairChan := make(chan TxnDataPair)

    go b.runBuildActor(txnDataPairChan)
    go b.runSendActor(txnDataPairChan)
}

The defined channel txnDataPairChan sends the transaction data pairs from the Builder to the Sender. Each transaction data pair comprises the batch transaction, and the data for each transaction is embedded in it. The data for each transaction is sent with the batch transaction so that the failed transactions can be sent back to the entity that instantiates the Batcher.

Builder

Let's analyze the Build actor. Note that the code is simplified for better readability (full code):

// This function builds a function call from the transaction data.
func (b *Batcher) buildFunctionCall(data []string) (*rpc.FunctionCall, error) {
        // Parse the recipient address
    toAddressInFelt, err := utils.HexToFelt(data[0])
    if err != nil {
        ...
    }

        // Parse the NFT ID
    nftID, err := strconv.Atoi(data[1])
    if err != nil {
        ...
    }

        // The entry point is a standard ERC721 function
        // https://docs.openzeppelin.com/contracts-cairo/0.20.0/erc721
    return &rpc.FunctionCall{
        ContractAddress: b.contractAddress,
        EntryPointSelector: utils.GetSelectorFromNameFelt(
            "safe_transfer_from",
        ),
        Calldata: []*felt.Felt{
            b.accnt.Address, // from
            toAddressInFelt, // to
            new(felt.Felt).SetUint64(uint64(nftID)), // NFT ID
            new(felt.Felt).SetUint64(0), // data -> None
            new(felt.Felt).SetUint64(0), // extra data -> None
        },
    }, nil
}

// This function builds the batch transaction from the function calls.
func (b *Batcher) buildBatchTransaction(functionCalls []rpc.FunctionCall) (rpc.InvokeTxnV1, error) {
        // Format the calldata (i.e., the function calls)
    calldata, err := b.accnt.FmtCalldata(functionCalls)
    if err != nil {
        ...
    }

    return rpc.InvokeTxnV1{
        MaxFee:        new(felt.Felt).SetUint64(MAX_FEE),
        Version:       rpc.TransactionV1,
        Nonce:         new(felt.Felt).SetUint64(0), // Will be set by the send actor
        Type:          rpc.TransactionTypeInvoke,
        SenderAddress: b.accnt.Address,
        Calldata:      calldata,
    }, nil
}

// Actual Build actor event loop
func (b *Batcher) runBuildActor(txnDataPairChan chan<- TxnDataPair) {
    size := 0
    functionCalls := make([]rpc.FunctionCall, 0, b.maxSize)
    currentData := make([][]string, 0, b.maxSize)

    for {
            // Boolean to trigger the batch building
        trigger := false

        select {
            // Receive new transaction data
        case data, ok := <-b.inChan:
            if !ok {
                ...
            }

            functionCall, err := b.buildFunctionCall(data)
            if err != nil {
                        ...
            }

            functionCalls = append(functionCalls, *functionCall)
            size++
            currentData = append(currentData, data)

            if size >= b.maxSize {
                        // The batch is full, trigger the building
                trigger = true
            }

            // We don't want a smaller batch to wait indefinitely to be full, so we set a timeout to trigger the building even if the batch is not full
        case <-time.After(WAITING_TIME):
            if size > 0 {
                trigger = true
            }
        }

        if trigger {
            builtTxn, err := b.buildBatchTransaction(functionCalls)
            if err != nil {
                        ...
            } else {
                        // Send the batch transaction to the Sender
                txnDataPairChan <- TxnDataPair{
                    Txn:  builtTxn,
                    Data: currentData,
                }
            }

                    // Reset variables
            size = 0
            functionCalls = make([]rpc.FunctionCall, 0, b.maxSize)
            currentData = make([][]string, 0, b.maxSize)
        }
    }
}

The runBuildActor function is the Builder actor's event loop. It waits for transactions to be sent to the Batcher and builds a batch transaction when the batch is full, or a timeout is reached. The batch transaction is then sent to the Sender actor.

Sender

Let's now analyze the Sender actor. Note that the code is simplified for better readability (full code):

// Actual Send actor event loop
func (b *Batcher) runSendActor(txnDataPairChan <-chan TxnDataPair) {
    oldNonce := new(felt.Felt).SetUint64(0)

    for {
            // Receive the batch transaction
        txnDataPair, ok := <-txnDataPairChan
        if !ok {
            ...
        }
        txn := txnDataPair.Txn
        data := txnDataPair.Data

            // Get the current nonce of the sender account
        nonce, err := b.accnt.Nonce(context.Background())
        if err != nil {
                    ...
        }

            // It might happen that the nonce is not directly updated if another transaction was sent just before. Therefore, we manually increment it to make sure this new transaction is sent with the correct nonce
        if nonce.Cmp(oldNonce) <= 0 {
            nonce.Add(oldNonce, new(felt.Felt).SetUint64(1))
        }

        txn.Nonce = nonce

            // Sign the transaction
        err = b.accnt.SignInvokeTransaction(context.Background(), &txn)
        if err != nil {
                    ...
        }

            // Send the transaction to the Starknet network
        resp, err := b.accnt.SendTransaction(context.Background(), &txn)
        if err != nil {
                    ...
        }

            // Monitor the transaction status
    statusLoop:
        for {
                    // Wait a bit before checking the status
            time.Sleep(time.Second * 5)

                    // Get the transaction status
            txStatus, err := b.accnt.Provider.TransactionStatus(
                context.Background(),
                resp.Hash,
            )
            if err != nil {
                        ...
            }

                    // Check the execution status
            switch txStatus.ExecutionStatus {
            case rpc.TxnExecutionStatusSUCCEEDED:
                oldNonce = nonce
                break statusLoop
            case rpc.TxnExecutionStatusREVERTED:
                        // A reverted transaction consumes the nonce
                oldNonce = nonce
                ...
                break statusLoop
            default:
            }

                    // Check the finality status
            switch txStatus.FinalityStatus {
            case rpc.TxnStatusReceived:
                continue
            case rpc.TxnStatusAcceptedOnL2, rpc.TxnStatusAcceptedOnL1:
                oldNonce = nonce
                break statusLoop
            default:
            }

                    // Loop until the transaction status is determined
        }
    }
}

The runSendActor function is the sender actor's event loop. It waits for the Builder to send batch transactions, signs them, sends them to the Starknet network, and monitors their status.

A note on fee estimation: one could estimate the fee cost of the batch transaction before sending it. The following code can be added after signing the transaction:

        fee, err := b.accnt.EstimateFee(
            context.Background(),
            []rpc.BroadcastTxn{txn},
            []rpc.SimulationFlag{},
            rpc.WithBlockTag("latest"),
        )
        if err != nil {
            ...
        }

This might be useful to ensure the fee is not too high before sending the transaction. If the estimated fee is higher than expected, one might also need to re-adjust the max fee field of the transaction if the estimated fee is higher than expected. But note that when any change is made to the transaction, it must be signed again!

However, note that you might get some issues when estimating fees if the throughput of transactions is quite high. This is because when a given transaction is just approved, there is a bit of delay in updating the account's nonce. Therefore, when estimating the fee for the next transaction, it might fail, thinking that the nonce is still the previous one. So, if you still want to estimate fees, then you might need to provide some sleep between each transaction to avoid such problems.

Towards a generic batcher

The batcher presented is specific to sending NFTs from the same contract. However, the architecture can easily be adapted to send any type of transaction.

First, the transaction data sent to the Batcher must be more generic and, therefore, contain more information. They must contain the contract address, the entry point selector, and the call data. The buildFunctionCall function must then be adapted to parse this information.

One could also go one step further by making the sender account generic. This would require more refactoring, as the transactions must be batched per sender account. However, it is feasible and would allow for a more versatile batcher.

However, remember that premature optimization is the root of all evil. Therefore, if you just need to send NFTs or a specific token such as ETH or STRK, the batcher presented is more than enough.

CLI tool

The repository code can be used as a CLI tool to send a bunch of NFTs by batch. The tool is easy to use, and you should be able to adapt it to your needs after reading this article. Please refer to the README for more information.

Conclusion

I hope that this article helped you to better understand how Metacube sends NFTs to its players. The batcher is a key infrastructure component, and we are happy to share it with the community. If you have any questions or feedback, feel free to comment or reach out to me. Thank you for reading!

A guide on Starknet signatures

Bastien Faivre — Sat, 20 Jul 2024 13:26:30 +0000

CHANGELOG

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

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

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

Go:

package main

import (
    "encoding/json"
    "fmt"
    "math/big"

    "github.com/NethermindEth/starknet.go/curve"
    "github.com/NethermindEth/starknet.go/typeddata"
)

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 := curve.PrivateKeyToPoint(privateKey)

    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.Sign(hash.BigInt(new(big.Int)), privateKey)
    if err != nil {
        fmt.Println("Error signing message:", err)
        return
    }
}

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 "@starknet-io/get-starknet";

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

// Request accounts from the wallet
const accounts = await starknet.request({ type: "wallet_requestAccounts" });
const accountAddress = accounts[0];

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!",
    },
};

// Sign the message using the wallet
const signature = await starknet.request({
    type: "wallet_signTypedData",
    params: messageStructure
});

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)

Go:

// following the previous code
isValid, err := curve.Verify(hash.BigInt(new(big.Int)), r, s, starknetPublicKey)
if err != nil {
    fmt.Println("Error verifying signature:", err)
    return
}

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 { RpcProvider, verifyMessageInStarknet, Signature } from "starknet";

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

// messageStructure, signature, and accountAddress are obtained from the previous code when signing the message with the browser wallet
const isValid = await verifyMessageInStarknet(
    provider,
    messageStructure,
    signature as Signature,
    accountAddress
);

console.log("Signature is valid:", isValid);

Go (simplified for readability):

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

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

...

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

// we import the account address and the signature from the frontend (typescript)
accountAddressInFelt, err := utils.HexToFelt("0xabc123")
if err != nil {
    // handle error
}

// signature is []*felt.Felt obtained from signing with the account
signature := []*felt.Felt{ /* ... */ }

// we need to get the message hash, but, this time, we use the account address instead of the public key. `ttd` is the same as 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))),
}

callData = append(callData, signature...)

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
}

isValid, err := hex.DecodeString(result[0].Text(16))
if err != nil {
    // handle error
}

fmt.Println("Signature is valid:", string(isValid) == "VALID")

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:

The user signs a message with the browser wallet.
Send the user address, message, and signature (string array) to the backend.
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. Thank you for reading!

Sources: