Skip to content

Ethereum Types

Ethereum type definitions.

Signature

Bases: BaseModel

Represents an Ethereum signature with v, r, s components.

Source code in web3_google_hsm/types/ethereum_types.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class Signature(BaseModel):
    """Represents an Ethereum signature with v, r, s components."""

    v: int = Field(..., description="Recovery identifier")
    r: bytes = Field(..., description="R component of signature")
    s: bytes = Field(..., description="S component of signature")

    @field_validator("r", "s")
    @classmethod
    def validate_length(cls, v: bytes) -> bytes:
        if len(v) != MSG_HASH_LENGTH:
            msg = f"Length must be 32 bytes, got {len(v)} bytes"
            raise ValueError(msg)
        return v

    @field_validator("v")
    @classmethod
    def validate_v(cls, v: int) -> int:
        if v < 0:
            msg = "v must be non-negative"
            raise ValueError(msg)
        return v

    def to_hex(self) -> str:
        """Convert signature to hex string."""
        return "0x" + (self.r + self.s + bytes([self.v])).hex()

    @classmethod
    def from_hex(cls, hex_str: str) -> "Signature":
        """Create signature from hex string."""
        if hex_str.startswith("0x"):
            hex_str = hex_str[2:]
        sig_bytes = bytes.fromhex(hex_str)
        if len(sig_bytes) != SIGNATURE_LENGTH:
            msg = f"Invalid signature length: {len(sig_bytes)}"
            raise ValueError(msg)
        return cls(v=sig_bytes[64], r=sig_bytes[0:32], s=sig_bytes[32:64])

from_hex(hex_str) classmethod

Create signature from hex string.

Source code in web3_google_hsm/types/ethereum_types.py 
44
45
46
47
48
49
50
51
52
53
@classmethod
def from_hex(cls, hex_str: str) -> "Signature":
    """Create signature from hex string."""
    if hex_str.startswith("0x"):
        hex_str = hex_str[2:]
    sig_bytes = bytes.fromhex(hex_str)
    if len(sig_bytes) != SIGNATURE_LENGTH:
        msg = f"Invalid signature length: {len(sig_bytes)}"
        raise ValueError(msg)
    return cls(v=sig_bytes[64], r=sig_bytes[0:32], s=sig_bytes[32:64])

to_hex()

Convert signature to hex string.

Source code in web3_google_hsm/types/ethereum_types.py 
40
41
42
def to_hex(self) -> str:
    """Convert signature to hex string."""
    return "0x" + (self.r + self.s + bytes([self.v])).hex()

Transaction

Bases: BaseModel

Represents an Ethereum transaction.

Source code in web3_google_hsm/types/ethereum_types.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
class Transaction(BaseModel):
    """Represents an Ethereum transaction."""

    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)

    chain_id: int = Field(..., description="Chain ID", validation_alias="chainId")
    nonce: int = Field(..., ge=0, description="Transaction nonce")
    gas_price: int = Field(..., gt=0, description="Gas price in Wei", validation_alias="gasPrice")
    gas_limit: int = Field(..., gt=0, description="Gas limit", validation_alias="gas")
    to: str = Field(..., description="Recipient address")
    value: int = Field(..., ge=0, description="Transaction value in Wei")
    data: str = Field("0x", description="Transaction data")
    from_: str = Field(..., description="Sender address", validation_alias="from")
    signature: Signature | None = Field(None, description="Transaction signature")

    @field_validator("to", "from_")
    @classmethod
    def validate_address(cls, v: str) -> str:
        if not is_address(v):
            msg = "Invalid Ethereum address"
            raise ValueError(msg)
        return to_checksum_address(v)

    @field_validator("data")
    @classmethod
    def validate_hex(cls, v: str) -> str:
        if not v.startswith("0x"):
            v = "0x" + v
        try:
            bytes.fromhex(v[2:])
        except ValueError as error:
            msg = "Invalid hex string"
            raise ValueError(msg) from error
        return v

    def to_dict(self) -> dict:
        """Convert transaction to dictionary format for web3.py."""
        tx_dict = {
            "chainId": self.chain_id,
            "nonce": self.nonce,
            "gasPrice": self.gas_price,
            "gas": self.gas_limit,
            "to": self.to,
            "value": self.value,
            "data": self.data,
            "from": self.from_,
        }
        return tx_dict

    def to_transaction_dict(self) -> dict:
        """Convert to dictionary format suitable for signing."""
        tx_dict = {
            "chainId": self.chain_id,
            "nonce": self.nonce,
            "gasPrice": self.gas_price,
            "gas": self.gas_limit,
            "to": self.to,
            "value": self.value,
            "data": self.data,
        }
        # Add signature if present
        if self.signature:
            tx_dict.update(
                {
                    "v": self.signature.v,
                    "r": int.from_bytes(self.signature.r, "big"),
                    "s": int.from_bytes(self.signature.s, "big"),
                }
            )
        return tx_dict

    @classmethod
    def from_dict(cls, data: dict) -> "Transaction":
        """
        Create transaction from dictionary.

        Args:
            data: Transaction data dictionary.

        Returns:
            Transaction: A new transaction instance

        Raises:
            ValueError: If required fields are missing or invalid
        """
        tx_data = data.copy()

        # Handle signature if present
        signature = None
        if all(k in tx_data for k in ["v", "r", "s"]):
            r_value = tx_data.pop("r")
            s_value = tx_data.pop("s")

            # Convert hex strings to bytes if necessary
            if isinstance(r_value, str):
                r_value = bytes.fromhex(r_value[2:] if r_value.startswith("0x") else r_value)
            if isinstance(s_value, str):
                s_value = bytes.fromhex(s_value[2:] if s_value.startswith("0x") else s_value)

            signature = Signature(v=tx_data.pop("v"), r=r_value, s=s_value)
            tx_data["signature"] = signature

        return cls(**tx_data)

    def serialize_transaction(self) -> bytes:
        """
        Serialize a transaction to bytes.

        Returns:
            bytes: The serialized transaction

        Raises:
            SignatureError: If transaction is not signed or signature verification fails
        """
        if not self.signature:
            msg = "The transaction is not signed."
            raise SignatureError(msg)

        # Create transaction dict without 'from' and with proper signature format
        txn_data = self.to_dict()

        if "from" in txn_data:
            txn_data.pop("from")

        # Create unsigned transaction dict
        unsigned_txn = serializable_unsigned_transaction_from_dict(txn_data)
        signature = (self.signature.v, to_int(self.signature.r), to_int(self.signature.s))

        signed_txn = encode_transaction(unsigned_txn, signature)

        # Verify signature
        recovered = Account.recover_transaction(signed_txn)
        if self.from_ and recovered.lower() != self.from_.lower():
            msg = f"Recovered signer doesn't match sender! Expected: {self.from_}, got: {recovered}"
            raise SignatureError(msg)

        return signed_txn

from_dict(data) classmethod

Create transaction from dictionary.

Parameters:

Name Type Description Default
data dict

Transaction data dictionary.

 required

Returns:

Name Type Description
Transaction Transaction

A new transaction instance

Raises:

Type Description
ValueError

If required fields are missing or invalid
Source code in web3_google_hsm/types/ethereum_types.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@classmethod
def from_dict(cls, data: dict) -> "Transaction":
    """
    Create transaction from dictionary.

    Args:
        data: Transaction data dictionary.

    Returns:
        Transaction: A new transaction instance

    Raises:
        ValueError: If required fields are missing or invalid
    """
    tx_data = data.copy()

    # Handle signature if present
    signature = None
    if all(k in tx_data for k in ["v", "r", "s"]):
        r_value = tx_data.pop("r")
        s_value = tx_data.pop("s")

        # Convert hex strings to bytes if necessary
        if isinstance(r_value, str):
            r_value = bytes.fromhex(r_value[2:] if r_value.startswith("0x") else r_value)
        if isinstance(s_value, str):
            s_value = bytes.fromhex(s_value[2:] if s_value.startswith("0x") else s_value)

        signature = Signature(v=tx_data.pop("v"), r=r_value, s=s_value)
        tx_data["signature"] = signature

    return cls(**tx_data)

serialize_transaction()

Serialize a transaction to bytes.

Returns:

Name Type Description
bytes bytes

The serialized transaction

Raises:

Type Description
SignatureError

If transaction is not signed or signature verification fails
Source code in web3_google_hsm/types/ethereum_types.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def serialize_transaction(self) -> bytes:
    """
    Serialize a transaction to bytes.

    Returns:
        bytes: The serialized transaction

    Raises:
        SignatureError: If transaction is not signed or signature verification fails
    """
    if not self.signature:
        msg = "The transaction is not signed."
        raise SignatureError(msg)

    # Create transaction dict without 'from' and with proper signature format
    txn_data = self.to_dict()

    if "from" in txn_data:
        txn_data.pop("from")

    # Create unsigned transaction dict
    unsigned_txn = serializable_unsigned_transaction_from_dict(txn_data)
    signature = (self.signature.v, to_int(self.signature.r), to_int(self.signature.s))

    signed_txn = encode_transaction(unsigned_txn, signature)

    # Verify signature
    recovered = Account.recover_transaction(signed_txn)
    if self.from_ and recovered.lower() != self.from_.lower():
        msg = f"Recovered signer doesn't match sender! Expected: {self.from_}, got: {recovered}"
        raise SignatureError(msg)

    return signed_txn

to_dict()

Convert transaction to dictionary format for web3.py.

Source code in web3_google_hsm/types/ethereum_types.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def to_dict(self) -> dict:
    """Convert transaction to dictionary format for web3.py."""
    tx_dict = {
        "chainId": self.chain_id,
        "nonce": self.nonce,
        "gasPrice": self.gas_price,
        "gas": self.gas_limit,
        "to": self.to,
        "value": self.value,
        "data": self.data,
        "from": self.from_,
    }
    return tx_dict

to_transaction_dict()

Convert to dictionary format suitable for signing.

Source code in web3_google_hsm/types/ethereum_types.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def to_transaction_dict(self) -> dict:
    """Convert to dictionary format suitable for signing."""
    tx_dict = {
        "chainId": self.chain_id,
        "nonce": self.nonce,
        "gasPrice": self.gas_price,
        "gas": self.gas_limit,
        "to": self.to,
        "value": self.value,
        "data": self.data,
    }
    # Add signature if present
    if self.signature:
        tx_dict.update(
            {
                "v": self.signature.v,
                "r": int.from_bytes(self.signature.r, "big"),
                "s": int.from_bytes(self.signature.s, "big"),
            }
        )
    return tx_dict