Notes on crypto-condition JSON format and API

README.md

We'd like to simplify creating complex conditions by allowing users to describe them as JSON.

const conditionDescription = {
  type: 'threshold-sha256',
  threshold: 2,
  subconditions: [{
    type: 'prefix-sha256',
    prefixUtf8: '...',
    subcondition: {
      type: 'ed25519',
      publicKey: '...'
    }
  }, {
    type: 'preimage-sha256',
    // Note that we could also provide the hash here instead of the preimage
    preimage: '...'
  }]
}

Generating a condition URI then becomes as simple as:

const executionCondition = cc.fromJson(conditionDescriptor).getConditionUri()

To get the fulfillment, we need to either provide a signature in the JSON, or we can let the crypto-conditions lib generate it for us:

const executionFulfillment = cc.fromJson(conditionDescriptor).sign(['...'], '')

Note that we're signing the threshold condition here. The sign method has the following signature:

sign(keys: PrivateKey[], message: Buffer | String)

It exists on the threshold, rsa, ed25519 and prefix conditions. In the case of the threshold condition, it'll simply call sign on all of its subconditions. In the case of a prefix condition, it'll prepend the prefix to the message and call sign on all of the subconditions.

Finally, in the case of a Ed25519 or RSA condition, it'll look for a private key that matches its public key in the provided key array. If it finds one, it'll generate a signature fulfilling itself.

Another way to fulfill a condition tree would be to provide an existing fulfillment to it:

executionFulfillment.fulfillSubcondition('cf:...')

This would also recurse to look for a condition that matches this fulfillment.

Another way of fulfilling a (preimage) condition is by providing a preimage to it:

executionFulfillment.supplyPreimage('...')

Once again, this method will be available on prefix and preimage condition types, recurse and fulfill any subconditions waiting for this preimage.

A typical flow of using this library would be to create a condition from a descriptor and then either generate a condition URI from it or fulfill it with a couple of sign and/or fulfill calls