docs(declaration,deployment): Enhance contract declaration and deployment documentation

[omarespejel]

Description of the Changes

Changes to Declaration Documentation

1. Enhanced Introduction

   • Added a clear explanation of what declaration means in Starknet
   • Introduced an analogy comparing declaration to registering a blueprint

2. Visual Representation

   • Added a Mermaid diagram showing the relationship between declaration and deployment

3. Context for Separation

   • Explained why declaration and deployment are separate steps in Starknet
   • Highlighted benefits like gas optimization and reusability

4. C++ Analogy

   • Included an analogy relating Starknet contract declaration to C++ concepts:
     • Writing contract code ≈ Defining a class in C++
     • Declaring contract ≈ Compiling class into object code
     • Deploying contract instance ≈ Creating an object of the class

5. Verification Methods

   • Using starkli class-by-hash command

Changes to Deployment Documentation

1. Expanded Introduction

   • Enhanced explanation of the deployment process
   • Added a factory production analogy for clearer understanding

2. Visual Representation

   • Included a Mermaid diagram illustrating the deployment process

3. Verification Methods

   • Using starkli class-hash-at command

4. Troubleshooting Guide

   • New section on common deployment issues, focusing on the "address unavailable" error
   • Explained the cause of the error (address collision due to salt reuse)
   • Provided solution (using unique salt values)

PR Preview URL

https://starknet-io.github.io/starknet-docs/pr-1359/

Check List

• Changes have been done against main branch, and PR does not conflict
• PR title follows the convention: <docs/feat/fix/chore>(optional scope): <description>, e.g: fix: minor typos in code

---

This change is 

[starknet-bot]

Oops, your pull request failed to pass the Typo tests stage :( . see the result:
error: paralell should be parallel
--> ./components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc:41:9
|
41 | Another paralell with Java:
| ^^^^^^^^
|

Please fix the typo, commit and push!

[starknet-bot]

Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1359/ .

[ArielElp]

Reviewed 3 of 4 files at r1, 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on @omarespejel)

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 24 at r2 (raw file):

* Deploying a contract, i.e. creating an instance of the code you previously declared.

image::declaration-process.png[]

Declare contract --> Declare contract class

I'd remove the "class hash" cube since it's confusing IMO. It's an implementation detail that you refer to classes via class_hash.

Alternatively, you can, under "Declare contract class", add a row in a smaller font of "class_hash: 0x12345", and in each deploy write "deploy instance i of the class 0x12345". Though the second option sounds a bit too much to me.

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 35 at r2 (raw file):

Declaration is the process of submitting your contract's code to the Starknet network, making it available for future deployments. It's a one-time process for each unique contract code. Think of declaration as registering a blueprint for your contract with the network.

We can draw a parallel with C++ programming:

I'd remove the c++ and java sections and say:

Contract classes are analogous to classes in Object Oriented Programming. The class is defined once, and there can be many instances of it.

anything more than that is too cumbersome in a "quick-start" page

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 49 at r2 (raw file):

Just as you can create multiple objects from a single class in C++, you can deploy multiple instances of a declared contract in Starknet.

=== Why Separate Declaration and Deployment?

Same here, quick-start shouldn't be about deep diving into the network. Maybe consider editing this page https://starknet-io.github.io/starknet-docs/pr-1359/architecture-and-concepts/smart-contracts/contract-classes/, and only linking to it here

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 184 at r2 (raw file):

This hash is the identifier of the contract class in Starknet. You can think of it as the address of the contract class. You can use a block explorer like https://testnet.starkscan.co/class/0x00e68b4b07aeecc72f768b1c086d9b0aadce131a40a1067ffb92d0b480cf325d[StarkScan] to see the contract class hash in the blockchain.

Using Starkli: You can use the following command to retrieve the contract class by its hash:

I think getting the raw class in a quickstart guide is too low-level.

---

components/Starknet/modules/quick-start/pages/deploy-a-smart-contract.adoc line 28 at r2 (raw file):

Deployment is the process of creating a live, functional instance of your declared smart contract on the Starknet network. It's like bringing a blueprint to life by constructing an actual building.

Let's use a factory production analogy:

I don't think the factory analogy should be in the quickstart guide. Potentially link to the contract classes page, but I suggest to remove this part.

---

components/Starknet/modules/quick-start/pages/deploy-a-smart-contract.adoc line 58 at r2 (raw file):

----

Think of <CLASS_HASH> as the product code in our factory analogy, and <CONSTRUCTOR_INPUTS> as the specific settings for this product instance.

Same as above, in favor of removing

[starknet-bot]

Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1359/ .

[omarespejel]

Reviewable status: 0 of 5 files reviewed, 6 unresolved discussions (waiting on @ArielElp)

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 24 at r2 (raw file):

Previously, ArielElp wrote…

Declare contract --> Declare contract class

I'd remove the "class hash" cube since it's confusing IMO. It's an implementation detail that you refer to classes via class_hash.

Alternatively, you can, under "Declare contract class", add a row in a smaller font of "class_hash: 0x12345", and in each deploy write "deploy instance i of the class 0x12345". Though the second option sounds a bit too much to me.

Done. I agree to keep it simple

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 35 at r2 (raw file):

Previously, ArielElp wrote…

I'd remove the c++ and java sections and say:

Contract classes are analogous to classes in Object Oriented Programming. The class is defined once, and there can be many instances of it.

anything more than that is too cumbersome in a "quick-start" page

Done.

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 49 at r2 (raw file):

Previously, ArielElp wrote…

Same here, quick-start shouldn't be about deep diving into the network. Maybe consider editing this page https://starknet-io.github.io/starknet-docs/pr-1359/architecture-and-concepts/smart-contracts/contract-classes/, and only linking to it here

Done.

---

components/Starknet/modules/quick-start/pages/declare-a-smart-contract.adoc line 184 at r2 (raw file):

Previously, ArielElp wrote…

I think getting the raw class in a quickstart guide is too low-level.

Done.

---

components/Starknet/modules/quick-start/pages/deploy-a-smart-contract.adoc line 28 at r2 (raw file):

Previously, ArielElp wrote…

I don't think the factory analogy should be in the quickstart guide. Potentially link to the contract classes page, but I suggest to remove this part.

Done.

---

components/Starknet/modules/quick-start/pages/deploy-a-smart-contract.adoc line 58 at r2 (raw file):

Previously, ArielElp wrote…

Same as above, in favor of removing

Done.

[omarespejel]

Thanks for the review @ArielElp!

[starknet-bot]

Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1359/ .

[starknet-bot]

Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1359/ .

[LandauRaz]

Hey @omarespejel, let's talk about this PR privately (closing it in the meantime).

[LandauRaz]

Partially addressed in #1416.

[starknet-bot]

Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1359/ .