Merge pull request #240 from onflow/contracts

Edit and consolidate Contracts articles

Author: briandoyle81

docs/language/accounts/contracts.mdx

@@ -3,331 +3,11 @@ title: Contracts
 sidebar_position: 5
 ---
 
-Accounts store [contracts](../contracts.mdx).
-A contract can also just be an [interface](../interfaces.mdx).
+Accounts store contracts. A contract can also just be an [interface](../interfaces.mdx).
 
-An account exposes its inbox through the `contracts` field,
-which has the type `Account.Contracts`.
+See [Contracts] for more information.
 
-## `Account.Contracts`
+<!-- Relative links. Will not render on the page -->
 
-```cadence
-access(all)
-struct Contracts {
-
-    /// The names of all contracts deployed in the account.
-    access(all)
-    let names: [String]
-
-    /// Returns the deployed contract for the contract/contract interface with the given name in the account, if any.
-    ///
-    /// Returns nil if no contract/contract interface with the given name exists in the account.
-    access(all)
-    view fun get(name: String): DeployedContract?
-
-    /// Returns a reference of the given type to the contract with the given name in the account, if any.
-    ///
-    /// Returns nil if no contract with the given name exists in the account,
-    /// or if the contract does not conform to the given type.
-    access(all)
-    view fun borrow<T: &Any>(name: String): T?
-
-    /// Adds the given contract to the account.
-    ///
-    /// The `code` parameter is the UTF-8 encoded representation of the source code.
-    /// The code must contain exactly one contract or contract interface,
-    /// which must have the same name as the `name` parameter.
-    ///
-    /// All additional arguments that are given are passed further to the initializer
-    /// of the contract that is being deployed.
-    ///
-    /// The function fails if a contract/contract interface with the given name already exists in the account,
-    /// if the given code does not declare exactly one contract or contract interface,
-    /// or if the given name does not match the name of the contract/contract interface declaration in the code.
-    ///
-    /// Returns the deployed contract.
-    access(Contracts | AddContract)
-    fun add(
-        name: String,
-        code: [UInt8]
-    ): DeployedContract
-
-    /// Updates the code for the contract/contract interface in the account.
-    ///
-    /// The `code` parameter is the UTF-8 encoded representation of the source code.
-    /// The code must contain exactly one contract or contract interface,
-    /// which must have the same name as the `name` parameter.
-    ///
-    /// Does **not** run the initializer of the contract/contract interface again.
-    /// The contract instance in the world state stays as is.
-    ///
-    /// Fails if no contract/contract interface with the given name exists in the account,
-    /// if the given code does not declare exactly one contract or contract interface,
-    /// or if the given name does not match the name of the contract/contract interface declaration in the code.
-    ///
-    /// Returns the deployed contract for the updated contract.
-    access(Contracts | UpdateContract)
-    fun update(name: String, code: [UInt8]): DeployedContract
-
-    /// Removes the contract/contract interface from the account which has the given name, if any.
-    ///
-    /// Returns the removed deployed contract, if any.
-    ///
-    /// Returns nil if no contract/contract interface with the given name exists in the account.
-    access(Contracts | RemoveContract)
-    fun remove(name: String): DeployedContract?
-}
-
-entitlement Contracts
-
-entitlement AddContract
-entitlement UpdateContract
-entitlement RemoveContract
-```
-
-## Deployed contract
-
-Accounts store "deployed contracts," that is, the code of the contract:
-
-```cadence
-access(all)
-struct DeployedContract {
-    /// The address of the account where the contract is deployed at.
-    access(all)
-    let address: Address
-
-    /// The name of the contract.
-    access(all)
-    let name: String
-
-    /// The code of the contract.
-    access(all)
-    let code: [UInt8]
-
-    /// Returns an array of `Type` objects representing all the public type declarations in this contract
-    /// (e.g. structs, resources, enums).
-    ///
-    /// For example, given a contract
-    /// ```
-    /// contract Foo {
-    ///
-    ///       access(all)
-    ///       struct Bar {...}
-    ///
-    ///       access(all)
-    ///       resource Qux {...}
-    /// }
-    /// ```
-    /// then `.publicTypes()` will return an array equivalent to the expression `[Type<Bar>(), Type<Qux>()]`
-    access(all)
-    view fun publicTypes(): [Type]
-}
-```
-
-Note that this is type only provides information about a deployed contract,
-it is not the contract instance, the result of importing a contract.
-
-## Getting a deployed contract
-
-The function `contracts.get` retrieves a deployed contract:
-
-```cadence
-access(all)
-view fun get(name: String): DeployedContract?
-```
-
-The function returns the [deployed contract](#deployed-contract) with the given name, if any.
-If no contract with the given name exists in the account, the function returns `nil`.
-
-For example, assuming that an account has a contract named `Test` deployed to it,
-the contract can be retrieved as follows:
-
-```cadence
-let account = getAccount(0x1)
-let contract = account.contracts.get(name: "Test")
-```
-
-## Borrowing a deployed contract
-
-Contracts can be "borrowed" to effectively perform a dynamic import dependent on a specific execution path.
-
-This is in contrast to a typical import statement, for example `import T from 0x1`,
-which statically imports a contract.
-
-The `contracts.borrow` function obtains a reference to a contract instance:
-
-```cadence
-access(all)
-view fun borrow<T: &Any>(name: String): T?
-```
-
-The functions returns a reference to the contract instance stored with that name on the account,
-if it exists, and if it has the provided type `T`.
-If no contract with the given name exists in the account, the function returns `nil`.
-
-For example, assuming that a contract named `Test`
-which conforms to the `TestInterface` interface is deployed to an account,
-a reference to the contract instance can obtained be as follows:
-
-```cadence
-let account = getAccount(0x1)
-let contract: &TestInterface = account.contracts.borrow<&TestInterface>(name: "Test")
-```
-
-This is similar to the import statement
-
-```cadence
-import Test from 0x1
-```
-
-## Deploying a new contract
-
-The `contracts.add` function deploys a new contract to an account:
-
-```cadence
-access(Contracts | AddContract)
-fun add(
-    name: String,
-    code: [UInt8],
-    ... contractInitializerArguments
-): DeployedContract
-```
-
-Calling the `add` function requires access to an account via a reference which is authorized
-with the coarse-grained `Contracts` entitlement (`auth(Contracts) &Account`),
-or the fine-grained `AddContract` entitlement (`auth(AddContract) &Account`).
-
-The `code` parameter is the UTF-8 encoded representation of the source code.
-The code must contain exactly one contract or contract interface,
-which must have the same name as the `name` parameter.
-
-The `add` function passes all extra arguments of the call (`contractInitializerArguments`)
-to the initializer of the contract.
-
-If a contract with the given name already exists in the account,
-if the given code does not declare exactly one contract or contract interface,
-or if the given name does not match the name of the contract declaration in the code,
-then the function aborts the program.
-
-When the deployment succeeded, the function returns the [deployed contract](#deployed-contract).
-
-For example, assuming the following contract code should be deployed:
-
-```cadence
-access(all)
-contract Test {
-
-    access(all)
-    let message: String
-
-    init(message: String) {
-        self.message = message
-    }
-}
-```
-
-The contract can be deployed as follows:
-
-```cadence
-transaction(code: String) {
-    prepare(signer: auth(AddContract) &Account) {
-        signer.contracts.add(
-            name: "Test",
-            code: code.utf8,
-            message: "I'm a new contract in an existing account"
-        )
-    }
-}
-```
-
-## Updating a deployed contract
-
-The `contracts.update` function updates the code of an existing contract:
-
-```cadence
-access(Contracts | UpdateContract)
-fun update(name: String, code: [UInt8]): DeployedContract
-```
-
-Calling the `update` function requires access to an account via a reference which is authorized
-with the coarse-grained `Contracts` entitlement (`auth(Contracts) &Account`),
-or the fine-grained `UpdateContract` entitlement (`auth(UpdateContract) &Account`).
-
-The `code` parameter is the UTF-8 encoded representation of the source code.
-The code must contain exactly one contract or contract interface,
-which must have the same name as the `name` parameter.
-
-If no contract with the given name exists in the account,
-if the given code does not declare exactly one contract or contract interface,
-or if the given name does not match the name of the contract declaration in the code,
-then the function aborts the program.
-
-When the update succeeded, the function returns the [deployed contract](#deployed-contract).
-
-:::warning
-
-The `update` function does **not** run the initializer of the contract again.
-
-Updating a contract does **not** change the contract instance and its existing stored data.
-A contract update only changes the code a contract.
-
-Is only possible to update contracts in ways that keep data consistency.
-[Certain restrictions apply](../contract-updatability.md).
-
-:::
-
-For example, assuming that a contract named `Test` is already deployed to the account,
-and it should be updated with the following contract code:
-
-```cadence
-access(all)
-contract Test {
-    
-    access(all)
-    let message: String
-
-    init(message: String) {
-        self.message = message
-    }
-}
-```
-
-The contract can be updated as follows:
-
-```cadence
-transaction(code: String) {
-    prepare(signer: auth(UpdateContract) &Account) {
-        signer.contracts.update(
-            name: "Test",
-            code: code
-        )
-    }
-}
-```
-
-## Removing a deployed contract
-
-The `contracts.remove` function removes a deployed contract from an account:
-
-```cadence
-access(Contracts | RemoveContract)
-fun remove(name: String): DeployedContract?
-```
-
-Calling the `remove` function requires access to an account via a reference which is authorized
-with the coarse-grained `Contracts` entitlement (`auth(Contracts) &Account`),
-or the fine-grained `RemoveContract` entitlement (`auth(RemoveContract) &Account`).
-
-The function removes the contract from the account which has the given name and returns it.
-If no contract with the given name exists in the account, the function returns `nil`.
-
-For example, assuming that a contract named `Test` is deployed to an account,
-the contract can be removed as follows:
-
-```cadence
-transaction(code: String) {
-    prepare(signer: auth(RemoveContract) &Account) {
-        signer.contracts.remove(name: "Test",)
-    }
-}
-```
+[Contracts]: ../contracts.mdx
+[interface]: ../interfaces.mdx