Merge pull request #1311 from ACStoneCL/1307_URef_Access_Rights

1307 Clarifying URef AccessRights

source/docs/casper/concepts/design/casper-design.md

@@ -136,6 +136,7 @@ In the case where there is a reference to stored on-chain Wasm (smart contracts)
 
 This key type is used for storing any value except `Account`. Additionally, `URef`s used in Wasm carry permission information to prevent unauthorized usage of the value stored under the key. The runtime tracks this permission information. This means that if malicious Wasm attempts to produce a `URef` with permissions that the Wasm does not have, the Wasm has attempted to "forge" the unforgeable reference, and the runtime will raise a forged `URef` error. Permissions for a `URef` can be given across contract calls, allowing data stored under a `URef` to be shared in a controlled way. The 32-byte identifier representing the key is generated randomly by the runtime (see [Execution Semantics](#execution-semantics-head) for more information). The serialization for `Access Rights` that define the permissions for `URefs` is detailed in the [CLValues](../serialization-standard.md) section.
 
+
 ### Permissions for `URef`s {#uref-permissions}
 
 In the runtime, a `URef` carries its permissions called `AccessRights`. Additionally, the runtime tracks what `AccessRights` would be valid for each `URef` in each context. The system assumes that a sent `URef` is invalid, regardless of declared `AccessRights`, and will check it against the executing context to determine validity on each usage. Only the host logic can add a `URef`, in the following ways:
@@ -266,7 +267,8 @@ The basic global state options map onto more standard monetary operations accord
 | Global State | Action Monetary Action                           |
 | ------------ | ------------------------------------------------ |
 | Add          | Deposit (i.e. transfer to)                       |
-| Write        | Withdraw (i.e. transfer from) Read Balance check |
+| Write        | Withdraw (i.e. transfer from)                    |
+| Read         | Balance check                                    |
 
 ## The mint Contract Interface {#tokens-mint-interface}
 

source/docs/casper/concepts/serialization-standard.md

@@ -741,6 +741,16 @@ A `Map` serializes as a list of key-value tuples. There must be a well-defined o
 | `ADD_WRITE`      |  6           |
 | `READ_ADD_WRITE` |  7           |
 
+    -   E.g. `uref-974019c976b5f26412ce486158d2431967af35d91387dae8cbcd43c20fce6452-007` shows a `URef` with full `READ_ADD_WRITE` rights.
+
+:::warning
+
+When passing a URef to another entity on chain, you must ensure that the `AccessRights` are set correctly. If the URef represents a [purse](./glossary/P.md#purse-purse), `AccessRights` impact who can deposit and withdraw CSPR.
+
+:::
+
+If a passed URef contains `ADD` permissions, the entity receiving the URef will then be able to deposit CSPR into the associated purse. `WRITE` permissions allow for withdrawing CSPR. As of 1.4.5, passing a main purse URef as a runtime argument will cause the host to automatically remove `WRITE` permissions. In this event, `READ` and `ADD` permissions will remain. Regardless, all due diligence should be performed to avoid passing a URef with `WRITE` permissions unintentionally.
+
 #### PublicKey {#clvalue-publickey}
 
 `PublicKey` serializes as a single byte tag representing the algorithm followed by 32 bytes of the `PublicKey` itself: