implement initial per-vat meter, vatAdmin meter object

[warner]

What is the Problem Being Solved?

In #3294 (comment) we sketched out a starting point for metering vat CPU usage. The overall goal is to effectively manage the scarce resource of CPU time, and to incentivize contract authors to write efficient code. There will be various economic mechanisms at the Zoe level (and above), but the swingset portion of the task begins with some fairly basic tools: simple meters, a way to set their CPU credits, and Zoe gets full control of all values. The authorities are pretty broad, but this should be enough to get us started.

Description of the Design

• in kernelKeeper, define a "meter table", which maps integer meter IDs (m${NN} for clarity) to a pair of numbers: the remaining capacity, and the notification threshold
  • these will be stored in the kernelDB, as a pair of keys like m${NN}.remaining and m${NN}.notify, whose values are integers (Nat)
  • add methods to get/set both
  • add a method to allocate a new meterID, which takes a remaining and notify, creates the keys, and returns the new meterID
• add a new "meter ID" field to the vat definition: kernelDB key v{$vatID}.meter which is either missing or holds a meterID
• change kernel.js > processQueueMessage:
  • before delivery, retrieve remaining and provide it as the per-crank metering limit
    • until xsnap should accept per-delivery metering thresholds #2980 is implemented, this will be ignored, but let's at least put the value in an obvious place to use it once that's done
    • we probably want the per-crank limit to the the min of remaining and the usual threshold: just because the vat has 20 minutes of CPU time available doesn't mean we want them consuming it all in a single crank
    • GC actions should probably be free and unrestricted by the remaining counter, since they don't give any userspace a chance to run, and it would be weird to kill a vat while userspace wasn't in control. But we need to think about this some more. For now, only message and notify deliveries interact with remaining.
  • after delivery, retrieve the CPU usage from the delivery results metering field
  • decrement the CPU usage from meterID.remaining
  • compare remaining against notify, invoke a meterRunningLow() function if lower (but only when remaining was higher/equal at the beginning of the delivery: don't spam the notifier)
• implement meterRunningLow to enqueue a message to vatAdminVat, just like kernel/notifyTermination.js does
• add kernel functions to allocate a new meter, and get/set the two values
• pass these kernel functions as additional endowments to vatAdminDevice (kernel.js start()), adding to the current pushCreateVatEvent, stats, and terminate endowments
• add vatAdminDevice methods to manipulate the meters
• add vatAdminVat methods to create a new "meter object" (a Remoteable, which maps through a WeakMap to the meterID), and has methods to get/set both values, and a Notifier that is triggered by the meterRunningLow message
• change the vatAdminVat createVatDynamically method to accept an options bag, with an optional meter object. If provided, look up the meterID and include it in the dynamicOptions bundle
• change processCreateVat to include the meterID in a renamed vatKeeper.setSourceAndOptions (maybe call it setInitialVatData({ source, options, meterID })), which should set the kernelDB key v${vatID}.meter if provided
• unit tests for everything

We should make new dynamic vats be unmetered by default, so existing code doesn't break. Zoe will decide which vats are worthly of infinite compute and which ones should be limited.

At this stage, we'll give Zoe complete control over the meters. Later, we can build something more sophisticated that:

• splits the ability to drain a meter (by associating it with a new vat) from the ability to refill it
• conserves CPU credits more carefully, perhaps modelled after ERTP, so there's a distinct Mint facet, but most users get something less powerful
• adds the ability to spawn a new meter off an existing one, claiming some of its credits

refs #3103 which is the larger (swingset-centric) question of how to measure/charge-for CPU usage, and #3294 which is the user-space (at least Zoe-space) question.

SwingSet vs Agoric Architectural Considerations

SwingSet is meant to be a standalone library for running vat-shaped computation. On its own, it knows nothing about tokens or contracts. In the agoric-sdk tree, we define two host applications (the chain nodes, and the ag-solo/wallet processes), and then layer a number of economic tools on top of those. We'll need to find an appropriate division of responsibility between the swingset layer and everything else we add on top.

I think SwingSet should know about metering, and provide authority-limited Meter objects (which manage CPU credits), but not have opinions about how the CPU credits are created or paid for. We can leverage the vatAdminVat to manage the meters, and then the question of how to pay for credits can remain inside whatever application-side code gets access to the vatAdminVat. We should provide enough support so that this application-specific layer does not need to e.g. wrap Meter objects with something less powerful. But the fact that CPU credits are purchased with RUN tokens, for example, is a deeply Agoric-centric concept, which SwingSet is better off not knowing about.

The notion of a Keeper, which can react to a meter underflowing, is pretty central, so I think that should be a part of the base SwingSet code. The auto-refill behavior of a Keeper is worth moving into the core, so we'll need to find some dividing line between a built-in "refill X computrons whenever the meter drops below threshold Y" behavior, and the fact that those X computrons must be acquired from something that knows about RUN and a current exchange rate.

Security Considerations

The ability to raise a meter's capacity (i.e. forge CPU credits) is roughly equivalent to the ability to deny service to other code, by starving them out of CPU time. The ability to reduce a meter's capacity is a much more direct way to deny service, equivalent to simply terminating the vat. Both deserve thoughtful representative and management.

The ability to read a meter's capacity also reveals noisy (but detailed) information about the computation that took place inside a vat. On a transparent public chain, this isn't a confidentiality threat, but it could create much more sensitivity to details of the JS engine or peer vat internals than we'd care for. As @mhofman pointed out, this is the vat equivalent of a timing side-channel attack. We should carefully consider whether e.g. the parent vat (who called vatAdminVat~.createVatDynamically()) should get to read this capacity, and/or the metered vat itself. (At present, xsnap only reveals the meter usage at the end of the delivery, but I can imagine us wanting to change that, and we should consider these issues carefully before doing so).

Test Plan

• test-state.js should exercise the creation and manipulation of meters by kernelKeeper methods
• dynamic vat creation tests (test/vat-admin/test-innerVat.js) should exercise both with- and without- meters
• other test/vat-admin/ tests should exercise the Meter objects provided by vatAdminVat and the methods which it offers to manipulate them
• the dynamic vat metering tests (test/metering/test-dynamic-vat-metered.js) should add some code to observe the remaining value being reduced after successful deliveries, and the firing of the Notifier if/when the meter drops below the configured notification threshold (for the first time)
  • note that many of the existing metering tests are meant to check that oversized deliveries will terminate the vat (protection against infinite loops), so we'll need to rearrange these to examine non-fatal metering checks as well

[warner]

@mhofman we can pair-program on this next week