Can capabilities with entitlements be published? Improve docs/error message

[jordanschalm]

Issue to be solved

I was attempting to publish an authorized capability, got an error, and wasn't able to determine whether the runtime allows this from the error message and documentation.

Code snippet

// Publish authorized capability for position creation              
let participantCap = FlowCreditMarket.account.capabilities.storage.issue<auth(EParticipant) &Pool>(FlowCreditMarket.PoolStoragePath)         
FlowCreditMarket.account.capabilities.unpublish(FlowCreditMarket.PoolParticipantPublicPath)                                                  
FlowCreditMarket.account.capabilities.publish(participantCap, at: FlowCreditMarket.PoolParticipantPublicPath) 

Error message

error: cannot publish capability of type `auth(A.0000000000000007.FlowCreditMarket.EPartic
  ipant)&A.0000000000000007.FlowCreditMarket.Pool` to the path                              
  /public/flowCreditMarketPoolParticipant_0x0000000000000007  

Documentation section

I read through a few docs and found this to be the most relevant to the error: https://cadence-lang.org/docs/language/capabilities#publishing-capabilities

For example, the following transaction issues a new storage capability and then publishes it under the path /public/vault, allowing anyone to access and borrow the capability and gain access to the stored vault. Note that the reference type is unauthorized, so when the capability is borrowed, only publicly accessible (access(all)) fields and functions of the object can be accessed:

The documentation says "the reference type is unauthorized", but it's unclear whether that means "the specific reference type used in this example is unauthorized" or "all public capability reference types are unauthorized".

Suggested Solution

My assumption is that the reason this is failing is that a capability authorized with any entitlement cannot be published, so the following is based on that assumption :)

• have the error message say "cannot publish authorized capability ..."
• explicitly state this constraint in the documentation