Documentation

# Far(), Remotable, and Marshaling

Let's look more closely at an eventual send between vats:

counter remote presence

In the exporting vat, we'll take the makeCounter Hardened JavaScript example and refine it to make remotable counters by marking them with Far:

const makeCounter = () => {
  let count = 0;
  return Far('counter', {
    incr: () => (count += 1),
    decr: () => (count -= 1),
  });
};

const publicFacet = Far('makeCounter', { makeCounter });
assert(passStyleOf(publicFacet) === 'remotable');

# Marshaling by Copy or by Presence

Recall that the first step in an eventual send is to marshal the method name and arguments. Marshalling (opens new window) is transforming a data structure into a format suitable for storage or transmission. The @endo/marshal (opens new window) package uses JSON (opens new window), but it can handle Javascript values that cannot be expressed directly as JSON, such as undefined and BigInts.

const m = makeMarshal(undefined, undefined, smallCaps);

const stuff = harden([1, 2, 3n, undefined, NaN]);
const capData = m.toCapData(stuff);
t.deepEqual(m.fromCapData(capData), stuff);

Also, while many forms of data are copied between vats, remotables are marshalled so that they become remote presences when unmarshaled. Another vat can then make and use the exported counters:

const counter = E(publicFacet).makeCounter();
const n = await E(counter).incr();
assert(n === 1);

# Pass Styles and harden

Calls to remote presences must only contain passable arguments and return passable results. A Passable is a hardened value that can be marshalled. There are four broad kinds of Passable:

  • Pass-by-copy primitive values: undefined, null, booleans true and false, numbers, BigInts (opens new window), strings, and symbols that are either well-known (opens new window) or registered (opens new window).
  • Acyclic pass-by-copy containers that recursively terminate in non-container passables. Such containers include CopyArrays like harden(['foo', 'bar']), CopyRecords like harden({ keys: [0, 1], values: ['foo', 'bar'] }), and CopyTaggeds representing types like CopySet, CopyBag, and CopyMap (which extend the passStyleOf level of abstraction with tag-specific shapes and semantics (opens new window))
  • Pass-by-reference "PassableCaps":
    • Remotables: objects that can be shared with remote systems which can then invoke methods using e.g. E() eventual send notation. Remotables are created by Far() and related functions.
    • Promises for Passables.
  • As a special case, Errors are treated as pass-by-copy data that can also contain other Passables.

Every object exported from a smart contract, such as publicFacet or creatorFacet, must be passable. All objects used in your contract's external API must be passable.

All Passables must be hardened. Consider what might happen if we had a remote item and we did not harden some pass-by-copy data that we passed to it:

let amount1 = { brand: brand1, value: 10n };
await E(item).setPrice(amount1); // Throws an error, but let's imagine it doesn't.
amount1.value = 20n;

Now amount1 is supposedly both in the local and the remote vat, but the value is 20n in the local vat but 10n in the remote vat. (Worse: the remote vat might be the same as the local vat.) Requiring harden() for pass-by-copy data leads to behavior across vats that is straightforward to reason about.

# passStyleOf API

import { passStyleOf } from '@endo/pass-style';

passStyleOf(passable) returns a PassStyle string that categorizes passable.

  • passable {Passable}
  • Returns: {PassStyle}

PassStyle values correspond with the different kinds of Passable:

  • Pass-by-copy primitive values: "undefined", "null", "boolean", "number", "bigint", "string", or "symbol".
  • Pass-by-copy containers: "copyArray", "copyRecord", or "copyTagged".
  • Pass-by-reference PassableCaps: "remotable" or "promise".
  • Pass-by-copy Errors: "error".

If passable is not passable (for example, because it has not been hardened or has a non-trivial prototype chain), then passStyleOf will throw an error.

Check `passStyleOf` when handling untrusted structured data

Just as you would use typeof to check that an argument is a string or number, use passStyleOf when you expect, say, a copyRecord; this prevents malicious clients from playing tricks with cyclic data etc.

# Far() API

import { Far } from '@endo/far';

Far(farName, objectWithMethods) marks an object as Remotable.

  • farName { String }
  • objectWithMethods { Object } - Optional.
  • Returns: A Remotable object.

The farName parameter gives the Remotable an interface name for debugging purposes, which only shows up when logged through the console, for example with console.log.

The optional objectWithMethods parameter should be an object whose properties are the functions serving as the object's methods. It MUST NOT already be hardened or even frozen (though Far() will harden it before returning successfully). If not provided, a new empty object will be used.

Before succeeding, the Far() function:

  • Checks that each of the object's property values are functions and throws an error otherwise.
    • Accessors (i.e., get() and set()) are not allowed.
  • Records the interface name in the object.
  • Hardens the object.

Avoid accidental exports

If an object should never be exposed to other vats, you should make it a point not to use Far() on it. If an object is not marked as a Remotable but is accidentally exposed, an error is thrown. This prevents any vulnerability from such accidental exposure.

← Notifiers and Subscriptions →