docs: StarkGate function/event reference, architecture topic, procedu…

…ral content. (#886)

* Adding a new topic with functions for StarkGate.

* Added blockToken

* Added deactivateToken

* Added more functions.

* Added getWithdrawalBridges.

* Renamed token-bridge.adoc to starkgate-bridge.adoc. Added entries to .htaccess.

* Add L2 functions.

* Added params to addExistingBridge.

* SME comment

* Minor fixes.

* Added more functions.

* More edits.

* Add getStatus

* Add Cancelling a deposit.

* Added deposit and depositReclaim

* Add table-striping to description lists for parameters and returns.

* Adding types to parameters.

* Adding event to `Deposit`

* Add depositWithMessage

* Updates to overview.

* Adding `depositWithMessage*` functions.

* SME comments

* depositWithMessage* functions.

* Moved desc of Manager and Registry to top of section.

* SME comments

* SME comments

* SME comments

* Added new topic: StarkGate architecture.

* Changed name of file from stargate_dev_reference.adoc to starkgate_function_reference.adoc; Removed info on adding a custom bridge from starkgate-adding_a_token.adoc.

* Updated starkgate_architecture.adoc.

* SME comments, cleaning up scattered links.

* Edit xref text for deposit function and event

* Edited name of reference doc

* Fixed broken xref.

* Added list of functions in each contract.

* Updated architecture topic.

* Removed the section on the Manager and the Registry. I don't think that this is helpful.

* Added AsciiDoc role to function heading in prep for adding style to make heading clearer.

* Updates to Architecture topic based on SME engineering and product feedback.

* Updates to function reference based on SME comments.

* Fixed typo.

* Added Visibility header.

* Consistency edits.

* Consistency edits.

---------

Co-authored-by: JameStark <113911244+JameStark@users.noreply.github.com>

.htaccess

@@ -194,6 +194,9 @@ RewriteRule ^docs/L1\-L2\ Communication/token\-bridge/$ /documentation/architect
 RewriteCond %{QUERY_STRING} ^$
 RewriteRule ^/develop/L1\-L2_Communication/token\-bridge/$ /documentation/architecture_and_concepts/Network_Architecture/token-bridge? [R=301,L]
 
+RewriteCond %{QUERY_STRING} ^$
+RewriteRule ^documentation/develop/L1\-L2_Communication/token\-bridge\.html$ /documentation/tools/starkgate_dev_reference? [R=301,L]
+
 RewriteCond %{QUERY_STRING} ^$
 RewriteRule ^docs/L1\-L2\ Communication/token\-bridge/index\.html$ /documentation/architecture_and_concepts/Network_Architecture/token-bridge? [R=301,L]
 

components/Starknet/modules/architecture_and_concepts/nav.adoc

@@ -12,9 +12,7 @@
 **** xref:Network_Architecture/starknet-state.adoc[Starknet state]
 **** xref:Network_Architecture/on-chain-data.adoc[Data availability]
 
-*** L1-L2 messaging
-**** xref:Network_Architecture/messaging-mechanism.adoc[L1-L2 messaging]
-**** xref:Network_Architecture/token-bridge.adoc[StarkGate bridge]
+*** xref:Network_Architecture/messaging-mechanism.adoc[L1-L2 messaging]
 
 ** Accounts
 *** xref:Accounts/introduction.adoc[What is an account?]

components/Starknet/modules/tools/nav.adoc

@@ -1,4 +1,4 @@
-* Developer tools and resources
+* Tools and resources
 
 ** xref:starknet-book.adoc[The Starknet Book]
 ** xref:devtools.adoc[Developer tools]
@@ -16,3 +16,14 @@
 ** xref:limits_and_triggers.adoc[Current limits and triggers]
 ** xref:ref_block_explorers.adoc[Block explorers]
 ** xref:audit.adoc[Audit providers]
+
+** StarkGate bridge developer's guide
+*** xref:starkgate-bridge.adoc[Overview]
+*** xref:starkgate_architecture.adoc[StarkGate architecture]
+*** Procedures
+**** xref:starkgate-adding_a_token.adoc[Adding a token]
+**** xref:starkgate-removing_a_token.adoc[Removing a token]
+// **** xref:starkgate-executing_on_deposit_automation.adoc[Executing automation when receiving a deposit]
+**** xref:starkgate-cancelling a deposit.adoc[Cancelling a deposit]
+//**** xref:starkgate-backward_compatibility.adoc[Backward compatibility]
+*** xref:starkgate_function_reference.adoc[StarkGate function reference]

components/Starknet/modules/tools/pages/starkgate-adding_a_token.adoc

@@ -0,0 +1,15 @@
+[id="StarkGate_adding_a_token"]
+= Adding a token to StarkGate
+
+You can add support for a token with the `enrollTokenBridge` function, using a block explorer or a CLI.
+
+The L2 ERC-20 contract is a standard contract, so it is not recommended to add tokens with non-standard behavior, such as inflationary tokens.
+
+include::partial$snippet_enrollTokenBridge_note.adoc[]
+
+Adding a token that requires a customized bridging mechanism or a non-standard ERC-20 contract on L2 is currently not pemissionless, and can be done only by the StarkWare team. Please contact StarkWare at info@starkware.co
+
+== Additional resources
+
+* xref:starkgate_function_reference.adoc#enrollTokenBridge[`enrollTokenBridge`] in the _StarkGate function reference_
+* xref:starkgate_architecture.adoc[StarkGate architecture]

components/Starknet/modules/tools/pages/starkgate-bridge.adoc

@@ -0,0 +1,135 @@
+[id="starkgate_token_bridge"]
+= StarkGate bridge overview
+
+StarkGate, developed by StarkWare, bridges ETH and ERC-20 tokens between Ethereum and Starknet. Each supported token is associated with an L1 and L2 bridge contract that communicates via Starknet's messaging mechanism.
+
+To use StarkGate, go to https://starkgate.starknet.io.
+
+A bridge enables you to fund your L2 wallet with ETH and ERC-20 tokens that reside on L1.
+
+The terms _deposit_, _transact_, and _transfer_ refer to various operations involving a bridge, even though ETH and ERC-20 tokens never actually leave Ethereum.
+
+[id="starkgate_alpha_limitations"]
+== StarkGate Alpha limitations
+
+In order to reduce the risks involved in using an Alpha version, StarkGate Alpha on Mainnet has limitations regarding the deposit amount and total value locked in the L1 bridge contract:
+
+[%autowidth.stretch,stripes=even]
+|===
+| Token | Max total value locked
+
+| ETH
+| 150,000 ETH
+
+| WBTC
+| 200 WBTC
+
+| USDC
+| 40,000,000 USDC
+
+| USDT
+| 20,000,000 USDT
+
+| DAI
+| 5,000,000 DAI
+
+| rETH
+| 10,000 rETH
+
+| wstETH
+| 5,000 wstETH
+
+|===
+
+[NOTE]
+====
+StarkWare plans to gradually ease these limitations and lift them completely, as confidence grows.
+
+Changes will be updated here.
+====
+
+[id="l1l2_transfer_deposit"]
+== L1→L2 transfer (deposit)
+
+[id="step_1_call_the_deposit_function_on_l1"]
+=== Step 1: Call the deposit function on L1
+
+
+. A call to the L1 `deposit` function initates a deposit.
+. The function does the following:
++
+--
+* Checks that the funds transferred are within the Alpha xref:starkgate-bridge.adoc#starkgate_alpha_limitations[limitations].
+* Transfers the funds from the user's account to the Starknet bridge.
+* Emits a `Deposit` event that includes the L1 and L2 addresses of the user, and the amount deposited.
+* Sends a message to the corresponding L2 bridge with the amount deposited, and the recipient's address.
+--
++
+Starknet's sequencer is now aware of the deposit transaction.
+
+. The sequencer waits for enough L1 block confirmations to fill its quota to run before the corresponding deposit transaction is initiated on L2. During this period of time, the status of the L2 deposit transaction is xref:architecture_and_concepts:Network_Architecture/transaction-life-cycle.adoc#not_received[`NOT_RECEIVED`].
+
+[id="step_2_deposit_triggered_on_starknet"]
+=== Step 2: Deposit triggered on Starknet
+
+. The sequencers refer to the deposit
+request by triggering the L1 handler using the
+https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/cairo/token_bridge.cairo#L135[`handle_deposit`] function on the L2 bridge.
+
+. The `handle_deposit` function verifies that the deposit indeed came from the corresponding L1 bridge. It then calls the relevant token's contract on Starknet and mints the specified amount of the token on L2 for the user.
+
+. The sequencers complete constructing the block.
+
+The status of the deposit request is now xref:architecture_and_concepts:Network_Architecture/transaction-life-cycle.adoc#accepted_on_l2[`ACCEPTED_ON_L2`].
+
+[id="step_3_the_block_that_includes_the_transfer_is_proved"]
+=== Step 3: The block that includes the transfer is proved
+
+. Starknet's provers prove the validity of the block and submit a state update to L1.
+
+. The message confirming transfer of the funds is cleared from the Starknet Core Contract, and the fact that the user has transferred their funds is part of the now finalized state of Starknet.
+
+[NOTE]
+====
+If the message wasn't on L1 to begin with, that is, if the deposit request was fraudulently created on Starknet, the state update would fail.
+====
+
+[id="l2l1_transfer_withdraw"]
+== L2→L1 transfer (withdrawal)
+
+[id="step_1_call_the_withdraw_function_on_l2"]
+=== Step 1: Initiate a withdrawal from L2
+
+. A call to the L2 `initiate_withdraw` function initiates a withdrawal.
+. The function does the following:
+* Burns the transferred amount of tokens from the balance of the withdrawal's initiator.
+* Sends a message to the relevant L1 bridge with the amount to be transferred and the recipient's address.
+
+
+[#proving_the_block_that_includes_the_withdrawal_transaction]
+=== Step 2: Proving the block that includes the withdrawal transaction
+
+// Once the sequencer completes the block construction, Starknet's provers prove the validity of the block and submit a state update to L1. The message from the previous step is then stored in the Starknet Core Contract.
+
+. The sequencer completes the block construction
+. Starknet's provers prove the validity of the block and submit a state update to L1.
+. The message from the previous step is stored in the Starknet Core Contract.
+
+[id="step_3_transferring_the_funds_on_l1"]
+=== Step 3: Transferring the funds on L1
+
+After the withdrawal message has been recorded on the Starknet Core Contract, anyone can finalize the transfer on L1 from the bridge back to the user, by calling the `withdraw` function.
+
+[NOTE]
+====
+This step is permissionless, anyone can do it. The recipient's address is part of the recorded message on L1, so they receive the funds regardless of who calls the `withdraw` function on L1.
+====
+
+== Additional resources
+
+* xref:architecture_and_concepts:Network_Architecture/messaging-mechanism.adoc[L1-L2 messaging]
+* The _StarkGate developer's reference_:
+** xref:starkgate_function_reference.adoc#deposit[`deposit` function, `Deposit` event]
+** xref:starkgate_function_reference.adoc#withdraw[`withdraw`]
+** xref:starkgate_function_reference.adoc#initiate_withdraw[`initiate_withdraw`]
+* link:https://github.com/starkware-libs/starkgate-contracts/blob/28f4032b101003b2c6682d753ea61c86b732012c/src/starkware/starknet/apps/starkgate/cairo/token_bridge.cairo#L135[`handle_deposit`] function on the L2 bridge

components/Starknet/modules/tools/pages/starkgate-cancelling a deposit.adoc

@@ -0,0 +1,35 @@
+[id="StarkGate_cancelling_a_deposit"]
+= Cancelling a deposit
+
+To ensure self-custody, StarkGate enables you to cancel a deposit if, after depositing funds with the `deposit` function on L1, you don't see your funds appear on L2 within a reasonable amount of time.
+
+You can only cancel a deposit that you yourself deposited.
+
+In order to guard against an attack, it takes approximately five days to cancel a deposit. From the moment StarkGate receives the cancellation request, a counter begins. When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit.
+
+
+// a deposit, and only before depositReclaim was performed.
+
+// If five days pass and the deposit request has still not been serviced, you can reclaim the deposit.
+
+.Procedure
+
+. To cancel a deposit, call the `depositCancelRequest` request function.
++
+When StarkGate receives the cancellation request, a counter begins to count five days.
+
+. When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit by calling `depositReclaim`.
+
+[NOTE]
+====
+As long as the `depositReclaim` was not performed, the deposit may be processed, even if
+the cancellation delay time has already passed.
+
+Only the depositor is allowed to cancel
+a deposit, and only before depositReclaim was performed.
+====
+
+== Additional resources
+
+* xref:starkgate_function_reference.adoc#depositCancelRequest[`depositCancelRequest`] in the _StarkGate function reference_.
+* xref:starkgate_function_reference.adoc#depositReclaim[`depositReclaim`] in the _StarkGate function reference_.

components/Starknet/modules/tools/pages/starkgate-removing_a_token.adoc

@@ -0,0 +1,8 @@
+[id="StarkGate_removing_a_token"]
+= Removing a token from StarkGate
+
+If you are a bridge provider, you can remove a token bridge using the `selfRemove` function.
+
+== Additional resources
+
+* xref:starkgate_function_reference.adoc#selfRemove[`selfRemove`] in the _StarkGate function reference_