Commands

Gummiworm sends the following commands to Sugar Rush while processing user requests:

type GummiwormCommand =
  | { "RegisterDeposit": RegisterDeposit }
  | { "ApplyDepositDecisions": ApplyDepositDecisions }
  | { "ApplyTransaction": ApplyTransaction }
  | { "ProxyBlockConfirmation": ProxyBlockConfirmation }
  | { "ProxyRequestError": ProxyRequestError }

Sugar Rush decrypts the L2 payloads according to the scheme described here.

Sugar Rush expects the decrypted L2 payloads to be JSON-encoded. It parses the L2 payloads for each command as described in deposit command and transaction command, respectively.

Responses to Gummiworm

Gummiworm expects Sugar Rush to validate the received commands and respond with these reports:

• If a RegisterDeposit command is valid, report successful registration. Otherwise, report that Sugar Rush determined the deposit request’s outcome as invalid with an error code.

• If an ApplyDepositDecisions command is received, report the evacuation map changes resulting from merging the absorbed deposits’ compartments into the main compartment.

• If an ApplyTransaction command is received, report the outcome:

  • If valid, report the resulting evacuation map changes and immediate L1 payouts.
  • If invalid, report the error code.

type GummiwormResponse =
  | { "Success": Success }
  | { "Failure": Failure }
 
type Success = {
  evacuationDiffs: EvacuationDiff[],
  payouts: TransactionOutput[],
}
 
type Failure = {
  message: string, // NB: Gummiworm ignores this
}
 
// hex-encoded
type ByteString = string
type Hash32 = ByteString
 
// CBOR-encoded
type TransactionOutput = ByteString

The evacuationDiffs field reports the changes to the evacuation map. Each diff is either an update or a delete of an entry, keyed by an opaque hash.

type EvacuationDiff =
  | Update
  | Delete
 
type Update = {
  tag: "Update",
  key: EvacuationDiffKey,
  value: TransactionOutput,
}
 
type Delete = {
  tag: "Delete",
  key: EvacuationDiffKey,
}
 
// Can be anything; here we pad the 28-byte `accountId` to 32 bytes
type EvacuationDiffKey = Hash32

If a RegisterDeposit or ApplyTransaction is invalid, Sugar Rush stores a human-readable error message in its DB, keyed by requestId. The UI can surface this message to the submitter.

Ledger events

Ledger events describe the ledger state transitions that Sugar Rush applies when it receives valid commands from Gummiworm. Invalid commands do not cause any state transitions in the Sugar Rush ledger, and thus have no corresponding ledger events.

Sugar Rush emits these ledger events to the data plane, which facilitates queries that are interested in the state transitions without distraction from commands.

Deposit command payload

Sugar Rush recognizes only L2 payload type for the RegisterDeposit command, which can be used for new or existing accounts. The L2 payload has the following fields:

• accountId: the account holder’s public key hash
• delegatedKey: an (optional) public key hash, which has a limited set of permissions on the account
• evacuationDestination: an (optional) destination (address and datum) where evacuated funds should be sent for that account

If evacuationDestination is not specified, refundDestination will be used instead.

Each deposit command’s non-empty delegatedKey, evacuationAddress, and evacuationDatum field values will overwrite the account’s corresponding fields.

Transaction command payloads

Sugar Rush recognizes these types of transaction commands:

• Place order — place an order.
• Cancel order — cancel an order with the given order ID.
• Cancel all orders — cancel all orders of a particular account.
• Update Destination — replace the address or datum on the destination; (If the current destination on the account has a script payment credential, only the datum may change.)
• Withdraw — withdraw some value from a given account to a given address with a given datum. (If the current destination on the account has a script payment credential, it must match the destination of the withdrawal)
• Create Market — create a new market, if signed by the administrator

Proxy commands

Sugar Rush ledger writes the Proxy* commands it receives from Gummiworm to SpaceTimeDB, without processing them. These commands exist only because it’s easier for Sugar Rush than Gummiworm to communicate with SpaceTimeDB.

ProxyBlockConfirmation carries the pre-signed refund transactions that Gummiworm produced for refunded deposits in a confirmed block.

type ProxyBlockConfirmation = {
  blockNumber: BlockNumber,
  refundTxs: RefundTx[],
}
 
type RefundTx = {
  requestId: RequestId,
  signedRefundTx: ByteString,
}

ProxyRequestError carries the human-readable error message for an invalid request, keyed by the request ID.

type ProxyRequestError = {
  requestId: RequestId,
  message: String,
}