From dbc9457e7048a49bad6d89c9828f916e2c4902b3 Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Mon, 31 Jul 2023 18:31:37 -0500 Subject: [PATCH] Refresh lifecycle CAP (#1373) * Refresh lifecycle CAP * Updates and add auth * Updated auth sections for lifecycle --- core/cap-0046-02.md | 245 ++++++++++++++++++-------------------------- 1 file changed, 99 insertions(+), 146 deletions(-) diff --git a/core/cap-0046-02.md b/core/cap-0046-02.md index a79a3173e..377a9e159 100644 --- a/core/cap-0046-02.md +++ b/core/cap-0046-02.md @@ -28,16 +28,13 @@ Users need a way to manage smart contracts on the network. This CAP allows users to deploy the smart contracts to the network and specifies the supported contract code kinds. -This CAP also lets the validators turn off all smart contract functionality if -some unexpected behavior is found in the protocol. - ## Specification ### XDR See the XDR diffs in the Soroban overview CAP, specifically those referring to `HOST_FUNCTION_TYPE_CREATE_CONTRACT` and -`HOST_FUNCTION_TYPE_INSTALL_CONTRACT_CODE`. +`HOST_FUNCTION_TYPE_UPLOAD_CONTRACT_WASM`. ## Semantics @@ -55,19 +52,25 @@ unique contract sources. This CAP defines two possible kinds of contract sources: -- WASM source: a blob of WASM code that is stored in a separate ledger entry and - is deduplicated based on contents. This is installed to ledger by the users. +- Wasm source: a blob of Wasm code that is stored in a separate ledger entry and + is deduplicated based on contents. This is uploaded to ledger by the users. - Built-in contract: this is a 'source' compiled into host directly that has a protocol-defined interface and behavior. +#### Contract executable + +The Contract executable contains a pointer to the Wasm source or a tag of a built-in +contract. + #### Contract instance Contract instance can be thought of as an instance of the contract 'class'. Contract instance consists of: -- Identifier: SHA-256 hash of a pre-image payload -- Source reference: a pointer to the WASM source or a tag of a built-in - contract +- A `ContractExecutable`. +- An optional `SCMap*` for users to store data +that should be tied to the lifetime of the instance (TODO: link to state +expiration CAP). A contract instance may own an arbitrary amount of ledger entries attributed to its identifier. Contracts that share the same source in no way may influence @@ -75,66 +78,50 @@ each other; from the perspective of a contract invoker there is no difference between calling the contracts with the same or different source references (besides the possible contract-defined behavior differences). -### Contract identifier preimage types - -This CAP defines the following supported contract identifier preimage kinds. The -use cases for every identifier type are described in the following sections. -Every preimage is a part of the `HashIDPreimage` union and has a unique tag -associated with it in order to ensure that there are no collisions with other -hashes in the protocol. - -- `ENVELOPE_TYPE_CONTRACT_ID_FROM_ED25519`: built from an `ed25519` public key - and the user-specified `uint256` salt. -- `ENVELOPE_TYPE_CONTRACT_ID_FROM_SOURCE_ACCOUNT`: built from a Stellar account - identifier and the user-specified `uint256` salt. -- `ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET`: built from a Stellar `Asset` +### Contract identifier preimage type + +`ENVELOPE_TYPE_CONTRACT_ID` is the `HashIDPreimage` type used for contract +identifiers. This unique tag is what ensures that there are no collisions with +other hashes in the protocol. It contains the `Hash` of the `networkID` to +ensure that every network has unique set of contract identifiers, along with a +`ContractIDPreimage`, which is a union that supports both +`CONTRACT_ID_PREIMAGE_FROM_ADDRESS` and `CONTRACT_ID_PREIMAGE_FROM_ASSET`. +- `CONTRACT_ID_PREIMAGE_FROM_ADDRESS`: built from an an `SCAddress` and the + user-specified `uint256` salt. +- `CONTRACT_ID_PREIMAGE_FROM_ASSET`: built from a Stellar `Asset` structure. -- `ENVELOPE_TYPE_CONTRACT_ID_FROM_CONTRACT`: built from another contract - identifier and contract-specified `uint256` salt. - -Every preimage must also include a `networkID` (a hash of the network -passphrase) which ensures that every network has unique set of contract -identifiers. -### Installing WASM sources using `InvokeHostFunctionOp` +### Uploading Wasm sources using `InvokeHostFunctionOp` -WASM contract sources can be installed to the network without instantiating a +Wasm contract sources can be uploaded to the network without instantiating a contract via `InvokeHostFunctionOp`(defined in [CAP-0046-04](./cap-0046-04.md)) -with `HOST_FUNCTION_TYPE_INSTALL_CONTRACT_CODE` host function type. +with `HOST_FUNCTION_TYPE_UPLOAD_CONTRACT_WASM` host function type in +`hostFunction`. -This function accepts `InstallContractCodeArgs` struct that contains the WASM +This function accepts `opaque wasm<>` that contains the Wasm contract code. -Installed contracts are stored in `ContractCodeEntry` ledger entries. These -entries are keyed by the hash of `InstallContractCodeArgs` used to install +Uploaded contracts are stored in `ContractCodeEntry` ledger entries. These +entries are keyed by the hash of the Wasm used to upload them. -Contract installation host function will compute the hash of -`InstallContractCodeArgs` and check if such a contract code already exists. If +The contract upload host function will compute the hash of +the Wasm and check if such a contract code already exists. If the entry exists, the operation will immediately succeed. If it doesn't, the new `ContractCodeEntry` will be created. -Host does not perform any validation on the installed contract code, besides +Core does not perform any validation on the uploaded contract code, besides checking its size. #### Max contract size setting -The maximum WASM contract size will be introduced as a `ConfigSettingEntry`(see +The maximum Wasm contract size will be introduced as a `ConfigSettingEntry`(see [CAP-0046-09](./cap-0046-09.md) for details on config entries). It is set during the protocol version upgrade using a new `ConfigSettingEntry`, with `configSettingID` == `CONFIG_SETTING_CONTRACT_MAX_SIZE_BYTES`, and -`contractMaxSizeBytes` == `16384`. The valid values for -`contractMaxSizeBytes` are[0, 256000] (inclusive). - -#### No contract-driven WASM installation - -This CAP does not specify a way to install WASM sources from within a -contract. - -This is done to encourage efficient code reuse and deduplication: if the -contract was allowed to install the WASM code, then we'd need to store it -twice (in the installer contract and in the source entry). +`contractMaxSizeBytes` == `65536`. The valid values for +`contractMaxSizeBytes` are [5000, UINT32_MAX] (inclusive). ### Instantiating contracts using `InvokeHostFunctionOp` @@ -142,86 +129,76 @@ Contracts can be instantiated via `InvokeHostFunctionOp` with `HOST_FUNCTION_TYPE_CREATE_CONTRACT` host function type. The function accepts `CreateContractArgs` struct that defines the input for -building the contract identifier preimage (`contractID` field) and the contract -source reference (`source` field). - -All the preimage types besides `ENVELOPE_TYPE_CONTRACT_ID_FROM_CONTRACT` can be -built from the `contractID` field. - -The source and identifier arguments are normally independent of each other with -an exception: identifiers that are built from `CONTRACT_ID_FROM_ASSET` may only -be used in conjunction with built-in token contract source. This handles the -special case of instantiating token contracts corresponding to the classic -Stellar assets (see more details in [CAP-0046-06](./CAP-0046-06.md)). +building the contract identifier preimage (`contractIDPreimage` field) and the +contract executable reference (`executable` field). + +`InvokeHostFunctionOp`'s `auth` vector will also require a +`SorobanAuthorizationEntry` with `credentials` that match the address in +`CreateContractArgs` used to derive the contractID (if the preimage is +`CONTRACT_ID_PREIMAGE_FROM_ASSET`, then no auth is required).`rootInvocation` +should be set to a `SorobanAuthorizedInvocation` where `function` is of type +`SOROBAN_AUTHORIZED_FUNCTION_TYPE_CREATE_CONTRACT_HOST_FN`. +`function.createContractHostFn` should be set to the `CreateContractArgs` used +under the `HOST_FUNCTION_TYPE_CREATE_CONTRACT` host function mentioned above. + +The executable and identifier arguments are normally independent of each other +with an exception: identifiers that are built from +`CONTRACT_ID_PREIMAGE_FROM_ASSET` may only be used in conjunction with built-in +token contract source. This handles the special case of instantiating token +contracts corresponding to the classic Stellar assets (see more details in +[CAP-0046-06](./CAP-0046-06.md)). The host builds the actual contract identifier by computing SHA-256 of the -`HashIDPreimage` corresponding to the `contractID`. If the contract identifier -already exists, the operation fails. - -If the identifier is new, the host will a new `ContractDataEntry` from -[CAP-0046-05](./CAP-0046-05.md) with a `SCV_STATIC` key type, and -`SCS_LEDGER_KEY_CONTRACT_CODE` key value. The value of the entry is -`SCContractCode` that either refers to the WASM code entry or to a built-in -contract (according to the value of `source` field in `CreateContractArgs`). - -#### ED25519-based contract identifiers - -Building a `ENVELOPE_TYPE_CONTRACT_ID_FROM_ED25519` preimage based on a public -ED25519 key has an a additional signature verification step as to make sure -that this key has authorized creating a contract on their behalf. - -The owner of the key must sign SHA-256 hash of `HashIDPreimage` of type -`ENVELOPE_TYPE_CREATE_CONTRACT_ARGS`, that includes the network id, `salt`, and -`CreateContractSource` args that must match the respective args of -`HOST_FUNCTION_TYPE_CREATE_CONTRACT` invocation. +`HashIDPreimage` corresponding to the `contractIDPreimage`. If the contract +identifier already exists, the operation fails. -#### Installation fused with instantiation - -One of the possible types of `CreateContractSource` is -`CONTRACT_SOURCE_INSTALLED`, that accepts `InstallContractCodeArgs`. This is a -convenience argument that allows to install the code and instantiate a contract -using that code in a single operation. - -The installation implementation is exactly the same as for the case when -`HOST_FUNCTION_TYPE_INSTALL_CONTRACT_CODE` function is called. The contract -will be instantiated with WASM code reference source type that points to the -hash of the newly installed contract. - -As mentioned in the installation section, if the contract code already exists in -the ledger, the operation will still succeed, but no code entry will be -created. +If the identifier is new, the host will create a new Persistent +`ContractDataEntry` from [CAP-0046-05](./CAP-0046-05.md) with a +`SCV_LEDGER_KEY_CONTRACT_INSTANCE` key value. The value of the entry is +`ScContractInstance` that either refers to the Wasm code entry or to a built-in +contract (according to the value of the `executable` field in `CreateContractArgs`). ### Instantiating a contract from a contract Factory contracts are quite popular already on other networks, so this CAP adds functionality to support them. -The following host functions are provided to instantiate contracts: +The following host functions are provided to instantiate contracts and upload Wasm: ```rust -// Instantiates a contract with the source referring to the provided wasm_hash. -fn create_contract_from_contract(wasm_hash: Object /* 32-bytes array */, - salt: Object /* 32-bytes array */) -> Object /* 32-bytes array */ -// Instantiates a contract with the source referring to the built-in token. -fn create_token_from_contract(salt: Object /* 32-bytes array */) -> Object /* 32-bytes array */ +// Uploads the Wasm. Returns the SHA-256 hash of the Wasm code. +fn upload_wasm(wasm: Bytes) -> Bytes + +// Creates a Wasm instance using the deployer, SHA-256 hash of the Wasm, and a user specified salt. +// Returns the Address of the newly created contract. +fn create_contract(deployer: Address, wasm_hash: Bytes, salt:Bytes) -> Address + +// Creates a Stellar Asset Contract for the XDR serialized asset passed in. Returns the Address +// for the newly created contract. +fn create_asset_contract(serialized_asset: Bytes) -> Address ``` -All of these functions return the identifier of the newly created contract. +The contractIDs for the contracts created with `create_contract` and +`create_asset_contract` are derived from `CONTRACT_ID_PREIMAGE_FROM_ADDRESS` and +`CONTRACT_ID_PREIMAGE_FROM_ASSET` respectively. + +Similar to how contract creation through `HOST_FUNCTION_TYPE_CREATE_CONTRACT` +requires authorization mentioned +[above](#instantiating-contracts-using-invokehostfunctionop), invoking the +`create_contract` host function requires authorization as well. -The identifier of the created contract is generated by hashing the -`HashIDPreimage` with type `ENVELOPE_TYPE_CONTRACT_ID_FROM_CONTRACT` with the -salt provided by the host function call. +### Updating a contracts code -### Validator override +We also provide a host function that allows contract instances to update the +Wasm executable by first uploading the new code, and then calling +`update_current_contract_wasm` with the hash of the newly uploaded Wasm.The +update happens only after the current contract invocation has successfully +finished, so this can be safely called in the middle of a function. -This proposal adds two new `LedgerHeader` flags that can disable the create and -invoke contract operations using upgrades. The validators can use this -mechanism in case unexpected behaviour is seen. We also considered adding a -mechanism for validators to opt accounts into smart contracts to allow for -a "soft" launch, but the implementation changes to get this to work are not -simple. The validators have the `LedgerHeader` overrides to fall back on, so -it's not clear that the complexity of adding a "soft" launch mechanism is worth -it. +```rust +// Updated the current contracts Wasm executable. +fn update_current_contract_wasm(wasm_hash: Bytes) +``` ## Design Rationale @@ -242,17 +219,17 @@ the contract creator chooses. ### `ContractCodeEntry` has no owner associated with it -Contract source code entries with the WASM code don't have any ownership. Anyone -can install contract sources to the ledger and then anyone can use them. This +Contract source code entries with the Wasm code don't have any ownership. Anyone +can upload contract sources to the ledger and then anyone can use them. This encourages sharing the contract code and allows contracts that use it to be sure that their implementation can't unexpectedly change. -### Contracts cannot be updated and deleted +### Contracts cannot be deleted, and can only be updated through the update_current_contract_wasm host function -The contract code reference is stored in a `ContractDataEntry`, but contract -code cannot be updated or deleted in the initial version. The host functions in -[CAP-0046-05](./CAP-0046-05#host-function-additions) to update or delete -`ContractDataEntry` should trap if they are used on contract code. +The contract code reference is stored in a `ContractDataEntry`, but the host +functions in [CAP-0046-05](./CAP-0046-05#host-function-additions) to set, +update, or delete `ContractDataEntry` should trap if they are used on contract +code. ### Malicious contracts @@ -260,7 +237,7 @@ The validators do not have a mechanism to ban specific contracts. Any kind of targeted banning mechanism can be worked around quite easily by creating new accounts and contracts. -### Maximum WASM contract code size is configurable +### Maximum Wasm contract code size is configurable The maximum contract size will be set during the protocol upgrade, and can be updated by the validators. This allows to adjust the contract sizes depending @@ -282,28 +259,4 @@ may not exist (for example, some general contracts like tokens or AMMs). The security concerns from CAP-0046 (https://github.com/stellar/stellar-protocol/blob/master/core/cap-0046.md#security-concerns) -apply here as well. - -In addition to those concerns, this CAP does not provide validators with much -control over contracts on the network. The only mechanism they have is blocking -all contract creations and invocations, which should only be used in drastic -situations. This CAP does not define a way for validators to block specific -contracts. - -## Potential Future Work - -### Mutable contracts support - -While the contracts are immutable in this CAP, it's already possible to make -them 'mutable' via proxy contracts (for example, contract A forwards its -method calls to contract B and ID of contract B is stored in the data of -the contract A). - -To further support mutation via the proxy pattern we could do the following: - -- Allow contract to modify its `SCS_LEDGER_KEY_CONTRACT_CODE` entry (as the - modification can only happen from within the contract, this would need to be - implemented in the first installed version of the contract) -- Allow specifying a contract ID as the contract's source reference, so that the - contract would be guaranteed to have exactly the same implementation as the - referred contract without any additional code. +apply here as well. \ No newline at end of file