URef 2.0

Grooming discussion recorded [here](https://drive.google.com/file/d/1gU5QYkTBamvKke0YlTLV8tqFKnaSvQvg/view?usp=share_link)

Backstory: "URef"s are user-land sharable keys - allows sharing data between accounts and contracts. They are:
- Not revokable;
- forever, never expires;
- primary key to a record in global state

Permissions:
- creator given read/write permission,
- permission is granted with sharing - access as same permissions or less.
- When shared, essentially a copy is shared with (level of access permissions or less).
- Share-ee can also share. Uncontrolled proliferation of something permanent in global state.

These same challenges are inherently shared with anything that is referenced via a uref (accounts, purses, etc). In general, Access control levels should not be permanent, otherwise they are not really "controlled". Once granted, they need to be modifiable.

We need to update URefs to remove the inherent limitations created by the existing implementations.
Existing urefs must be grandfathered. New implementation will be ONLY for URefs generated post 2.0.

**Adding Expiry**
- New urefs will expire by default- lifetime must be set on creation. Lifetime is number of eras as cost will be set according to the number of eras.
- Expiry is at end of era, when it is pruned if expired. Allows more data to be purged. Note: EE doesn't have a concept of 'era' so it will be a forward calculation of block-time.
- Cost is set based on lifetime requested (more eras, more cost); economics will be set to motivate cost effective usage: longer lifetimes are more expensive because they are held in global state longer.
- Lifetime can be extended by 'refreshing' the URef. This requires a new FFI to access the URef and update the lifetime. A deploy will be sent to make this change in global state
- TODO: Need to define lifetime settings we will allow: block, session, contract are all viable options
- **Enhancement**: Permanent lifetime is possible but very expensive?

**Share-ability: today they are infinitely sharable.**
- New property "sharing" set on creation - New default: "limited sharable" or "uref not shareable".
- TODO: Need to define how this is limited. Maybe: share N times - implemented via a counter N on the number of shares
- Existing URefs are infinitely sharable - Infinite is possible, but very expensive.
- URefs will be shared at the same permission level or less. Consider: sharing will share at the least permission but can be increased (basically a reverse of what exists today). BIG breaking change.

**[Story]: Add privately scoped mono-typed keys as an alternative to URef (which doesn't have all the baggage).**
- Offers contract writers an alternative to URefs to keep track of local "stuff". Stretch feature. Not to be considered until after Uref rework is complete (separate Epic)
- Right now: anything put into global state has to use a URef. COULD add support for a non-sharable, context bound, key. Similar to the old notion of local-key (which created a different set of challenges and was removed in favor of dictionaries). Dictionaries use a base hash made of an arbitrary URef addr + hash of a unique identifying sub-key to generate a hash (not contract or account hash).
- New solution (trait) would be similar to a dictionary (but different): Allow a URef to have a single stored value to use as a seed. Thus contract package versions would use the same seed to maintain access to their local keys.

**[Spike]: Making purses not URefs**
- History: inner (mint held) uref and outer uref (purse owner). Later created a new balance key variant (has an inner payload same as a uref). Purse is an outer key addr which points to an inner "unit" which has the same inner payload as a uref. Only the mint knows how to access this balance-tagged key. Now: managed via strong types. Use strong typing to separate "purse" from URefs.
- On upgrade to 2.0: Find existing purse urefs, put them into a new variant key entry called 'purse'. Use the expiry feature to add expiry date to the uref of the old 'purse' uref.
- Separates out purses from other urefs and allows us to implement proper commutative subtraction on urefs, because we know there are no longer any urefs that are purses - and allows transfers to be an atomic transaction. Only way to tell if a uref is a purse is to call get-balance and see if it errors.... Will need updates to purse documentation.
- Stretch feature - remove 'zombie' purses: Existing purses have to be retained. COULD mark the purse for purging later - for example, add a field to mark when the purse was last used. zero balance purses that have not been used in a long while can be purged.

What about named keys --> being replaced by a dictionary. Separate key space for each combinatorials. That is, anywhere we are using named keys, create a dictionary-like type for that use case. New Epic. Will allow for iteration using the key-space iterator. Needed for auction work. May be part of account/contract unification.

_extension of key enum used for bid rework may be relevant to the solve for named keys esp if we want to move with a dictionary-like solve for named keys_

Add a trait to URef to make them shareable but not forwardable.
---> This new trait will enable whitelists to verify callers, especially when a contract calls another.
Make it sharable by the originator but not to share-ee. Controlled by the sharing limit set when it is created and economics will enforce.

System does not keep track of who created a URef. New implementation will allow us to keep track of the context and entity that created it for ease of audit and reporting. Stronger notion of the creator == owner.

This will break any public facing function that uses URefs - LOTS of testing.

**end of recording**
**below are legacy notes and may no longer be relevant - Review with architect before proceeding on anything below**

URefs are the mechanism that controls shared ownership. Today: contract that creates the wrapped token owns the token; stored in contract context not account context, where ownership is more intuitive. Introduce 'move' semantic: instead of a tracking receipt to represent ownership, host would remove access from current owner and give it to the new owner. Differentiates 'shared' ownership (today) from 'true' ownership. stretch feature - function on host behind an FFI. Easily enabled once URef is refactored and Named keys migrated to dictionaries.

Needs to be done. Ed needs to do this. URefs need to do the following:
- Expire Urefs- all new ones will be removed from tip when expired.
- Add a new key that is context bound that cannot be shared.
- This new key will cost less. Will become the new default option.
- With this key, you can issue a URef against this key as an access token.
- The new URef contains the permissions and attach an expiry to it.
-
- none of the above is possible today with URefs, which seriously undermines their usability"
- will add ability to revoke (remove) items from a dictionary (seed uref no longer immutable) - need to carry this through. Source: contract limited (controlled access) minting modality to support contract whitelisting.

Start with the linked grooming discussion and review the existing URef implementation, including grandfathering requirements and the public-facing functions that will break. Separate the expiry, sharing, creator-tracking, purse, named-key, and local-key proposals before proceeding. Done requires an agreed scope and architecture, compatibility treatment for existing URefs, and a testing plan for the breaking changes.

Written by the indexing model from the issue text.