docs: contact classes (#36)

* classes documentation

docs/Blocks/transactions.md

@@ -6,7 +6,11 @@ StarkNet, in its Alpha version, supports two types of transactions: a `Deploy` t
 
 ## Deploy transaction
 
-A deploy transaction is a transaction type used to deploy contracts to StarkNet [^1]
+:::caution
+The deploy transaction will be deprecated in future StarkNet versions. To deploy new constract instances, you can use the `deploy` syscall. For more information, see [contract classes](../Contracts/contract-classes).
+:::
+
+A deploy transaction is a transaction type used to deploy contracts to StarkNet.
 
 A deploy transaction has the following fields:
 
@@ -15,32 +19,34 @@ A deploy transaction has the following fields:
 | Name                    | Type                 | Description                                                                      |
 | ----------------------- | -------------------- | -------------------------------------------------------------------------------- |
 | `contract_address_salt` | `FieldElement`       | A random number used to distinguish between different instances of the contract  |
-| `contract_code`         | `FieldElement`       | A path to the json containing the contract’s definition                          |
+| `contract_definition`   | `ContractClass`      | The object that defines the contract's functionality                             |
 | `constructor_calldata`  | `List<FieldElement>` | The arguments passed to the constructor during deployment                        |
 | `caller_address`        | `FieldElement`       | Who invoked the deployment. Set to 0 (in future: the deploying account contract) |
+| `version`               | `FieldElement`       | The transaction's version [^1]                                                   |
 
 </APITable>
 
-### Transaction hash
+### Calculating the hash of a deploy transaction
 
 In order to calculate the transaction hash, we first need to obtain the deployed contract address.
 
 The Deploy transaction’s hash is calculated as follows:
 
 $$
 \begin{aligned}
-\text{deploy\_tx\_hash} = h( & \text{"deploy"}, \text{contract\_address}, sn\_keccak(\text{“constructor”}),\\ & h(\text{constructor\_calldata}), \text{chain\_id})
+\text{deploy\_tx\_hash} = h( & \text{"deploy"}, \text{version}, \text{contract\_address}, sn\_keccak(\text{“constructor”}),\\ & h(\text{constructor\_calldata}), 0, \text{chain\_id})
 \end{aligned}
 $$
 
 Where:
 
+- The placeholder zero is used to align the hash computation for the different types of transactions (here, it holds the place of the `max_fee` field which exsists in both `invoke` and `declare` transactions)
 - “deploy” and “constructor” constant’s prefixes, encoded in bytes (ASCII), with big-endian.
 - $h$ is the [Pedersen](../Hashing/hash-functions#pedersen-hash) hash and $sn\_keccak$ is [StarkNet Keccak](../Hashing/hash-functions#starknet-keccak)
-- `chain_id` is a constant value specifying the network this transaction is sent to. See [below](./transactions#chain-id).
-- `contract_address` is calculated as described here.
+- `chain_id` is a constant value that specifies the network to which this transaction is sent. See [Chain-Id](./transactions#chain-id).
+- `contract_address` is calculated as described [here](../Contracts/contract-address).
 
-## Invoke Function
+## Invoke Transaction
 
 The invoke function transaction is the main transaction type used to invoke contract functions in StarkNet.
 
@@ -55,7 +61,7 @@ An invoke function transaction has the following fields:
 | `calldata`             | `List<FieldElement>` | The arguments passed to the invoked function                                              |
 | `signature`            | `List<FieldElement>` | Additional information given by the caller, representing the signature of the transaction |
 | `max_fee`              | `FieldElement`       | The maximum fee that the sender is willing to pay for the transaction                     |
-| `version`              | `FieldElement`       | The intended StarkNet OS version                                                          |
+| `version`              | `FieldElement`       | The transaction's version [^1]                                                            |
 
 </APITable>
 
@@ -67,7 +73,7 @@ in the StarkNet OS, we can prevent old transactions from being executed in this
 
 :::
 
-### Transaction hash
+### Calculating the hash of an invoke transaction
 
 The invoke function transaction hash is calculated as a hash over the given transaction elements, specifically:
 
@@ -80,21 +86,54 @@ $$
 Where:
 
 - “invoke” is a constant prefix, encoded in bytes (ASCII), with big-endian.
-- `chain_id` is a constant value specifying the network this transaction is sent to. See [below](./transactions#chain-id).
+- `chain_id` is a constant value that specifies the network to which this transaction is sent. See [Chain-Id](./transactions#chain-id).
 - $$h$$ is the [Pedersen](../Hashing/hash-functions#pedersen-hash) hash
 
-### Signature
+## Declare transaction
+
+The declare transaction is used to introduce new classes into the state of StarkNet, enabling other contracts to deploy instances of those classes or using them in a library call. For more information, see [contract classes](../contracts/contract-classes).
+
+A declare transaction has the following fields:
+
+<APITable>
+
+| Name             | Type                 | Description                                                                               |
+| ---------------- | -------------------- | ----------------------------------------------------------------------------------------- |
+| `contract_class` | `ContractClass`      | The class object                                                                          |
+| `sender_address` | `FieldElement`       | The address of the account initiating the transaction                                     |
+| `max_fee`        | `List<FieldElement>` | The maximum fee that the sender is willing to pay for the transaction                     |
+| `signature`      | `List<FieldElement>` | Additional information given by the caller, representing the signature of the transaction |
+| `nonce`          | `FieldElement`       | The transaction nonce                                                                     |
+| `version`        | `FieldElement`       | The transaction's version [^1]                                                            |
+
+</APITable>
+
+### Calculating the hash of a declare transaction
 
-While StarkNet does not have a specific signature scheme built into the protocol, the Cairo language in which smart contracts are written does have an efficient implementation for ECDSA signature with respect to a [STARK-friendly curve](../Hashing/hash-functions#stark-curve).
+The declare transaction hash is calculated as a hash over the given transaction elements, specifically:
+
+$$
+\begin{aligned}
+\text{invoke\_tx\_hash} = h( & \text{"declare"}, \text{version}, \text{sender\_address}, \\& 0, 0, \text{max\_fee}, \text{chain\_id}, \text{class\_hash})
+\end{aligned}
+$$
+
+Where:
+
+- The placeholders zeros are used to align the hash computation for the different types of transactions (here, they stand for the empty call data and entry point selector)
+- `chain_id` is a constant value that specifies the network to which this transaction is sent. See [Chain-Id](./transactions#chain-id).
+- $$h$$ is the [Pedersen](../Hashing/hash-functions#pedersen-hash) hash
+
+## Signature
+
+While StarkNet does not have a specific signature scheme built into the protocol, the Cairo language, in which smart contracts are written, does have an efficient implementation for ECDSA signature with respect to a [STARK-friendly curve](../Hashing/hash-functions#stark-curve).
 
 The generator used in the ECDSA algorithm is $G=\left(g_x, g_y\right)$ where:
 
 $g_x=874739451078007766457464989774322083649278607533249481151382481072868806602$
 $g_y=152666792071518830868575557812948353041420400780739481342941381225525861407$
 
-[^1]: Note, this type of transaction may be deprecated as StarkNet matures, effectively incorporating this into an invoke function transaction over an account contract which will implement the deployment as part of its functionality.
-
-### Chain-Id
+## Chain-Id
 
 StarkNet currently supports two chain IDs. Chain IDs are given as numbers, representing an encoding of specific constants as bytes (ASCII) using big-endian, as illustrated by the following Python snippet:
 
@@ -106,3 +145,5 @@ Two constants are currently used:
 
 - `SN_MAIN` for StarkNet’s main network.
 - `SN_GOERLI` for StarkNet's testnet.
+
+[^1]: The StarkNet OS defines the supported transaction versions (e.g. if a new field is added to the transaction, then the version is increased). A transaction whose version is not supported by the StarkNet OS can not be included in a block.

docs/Contracts/contract-classes.md

@@ -0,0 +1,13 @@
+# Contract Classes
+
+Taking inspiration from object-oriented programming, StarkNet distinguishes between a contract and its implementation by separating contracts into classes and instances.
+
+A contract class is the definition of the contract: Cairo byte code, hint information, entry point names, and everything that defines its semantics unambiguously. Each class is identified by its class hash, which is analogous to a class name in an object oriented programming language. A contract instance is a deployed contract corresponding to some class. Notice that only contract instances behave as contracts in that they have their own storage and can be called by transactions or other contracts.
+
+A contract class does not necessarily have a deployed instance in StarkNet.
+
+## Using Classes
+
+New classes can be added to the state of StarkNet with the [`declare`](../Blocks/transactions#declare-transaction) transaction. New instances of a previously declared class can be deployed via the `deploy` system call.
+
+To use the functionality of a declared class, without deploying an instance of that class, you can use the `library_call` system call. This system call is an analogue of Ethereum's delegate call in the world of classes. You can use class code directly, instead of having a placeholder contract deployed, which is used only for its code.

docs/State/starknet-state.md

@@ -1,16 +1,20 @@
 # StarkNet State
 
-The state of StarkNet is a mapping between addresses (251 bit field elements) and contract’s state.
+The state of StarkNet consists of:
 
-The contract state consists of:
+- contract instances: a mapping between addresses (251 bit field elements) and contract’s state.
+- [contract classes](../Contracts/contract-classes): a mapping between class hash and the class definition
 
-- Contract code
-- [Contract storage](../Contracts/contract-storage) (a key-value mapping where the key/values are field elements)
+A contract state consists of:
+
+- class_hash (defines the functionality)
+- [contract storage](../Contracts/contract-storage) (a key-value mapping where the key/values are field elements)
 
 With the above definition, we can provide a brief sketch of StarkNet’s transition function. A transaction $tx$ transitions the system from state $S$ to state $S’$ if:
 
-- $tx$ is an invoke transaction, and the storage of $S’$ is the result of executing the target contract code with respect to the previous state $S$ (the arguments, contract address, and the specific entry point are part of the transaction)
-- $tx$ is a deploy transaction, and $S’$ contains the new contract’s state at the contract’s address. Additionally, the storage of $S$ is updated according to the execution of the contract’s constructor.
+- $tx$ is an [invoke](../Blocks/transactions#invoke-transaction) transaction, and the storage of $S’$ is the result of executing the target contract code with respect to the previous state $S$ (the arguments, contract address, and the specific entry point are part of the transaction)
+- $tx$ is a [deploy](../Blocks/transactions#deploy-transaction) transaction, and $S’$ contains the new contract’s state at the contract’s address. Additionally, the storage of $S$ is updated according to the execution of the contract’s constructor.
+- $tx$ is a [declare](../Blocks/transactions#declare-transaction) transaction, and $S'$ contains the class hash and definition in the contract classes mapping
 
 ## State Commitment
 
@@ -26,6 +30,10 @@ Where:
 - $\text{storage\_root}$ is the root of another Merkle-Patricia tree of height 251 that is constructed from the contract’s storage
 - $h$ is the [Pedersen](../Hashing/hash-functions#pedersen-hash) hash function.
 
+:::info
+Note that, as of the time of writing, the commitment does not include classes information. This will be added in future versions.
+:::
+
 ### Merkle-Patricia tree
 
 #### Specifications