"Failure: require-capability: not granted" How do I grant a capability to my module?

Question

I've got a very simple function (increase-count), and I do not want this to be callable by anybody except code in the module. For this, I am using (require-capability (PRIVATE)). As expected, I get the following error.

Error from (api.testnet.chainweb.com): : Failure: require-capability: not granted: (free.guard-test-01.PRIVATE)

How do I grant my module the PRIVATE capability?

(defcap PRIVATE ()
    true
)



(defun increase-count (key:string)
    ;increase the count of a key in a table by 1
    (require-capability (PRIVATE))
    (update counts-table key {"count": (+ 1 (get-count key))})
) 

Answer 1

surround the call increase-count like this:

(with-capability (PRIVATE) (increase-count "abc"))

more in general:

• (with-capability (CAP) expr) will evaluate CAP to see whether you can grant it (this is the place where acquisition can fail), and then expr will be evaluated with CAP in scope if you successfully acquire it.
• (require-capability (CAP)) is then what you use within the scope of the functions you're trying to enforce CAP is present before you can proceed