Data Types

Ballot was Holium's first attempt at a production-grade app written in the Hoon language. It was a design decision early on in the development process to make heavy of use of json. There were a few different reasons for this decision:

  • the json structures in hoon are extremely flexible. json gave us a generalized key/value pair store with support for multiple value types (e.g. string %s, object %o, number %n, array %a, etc.). This was very powerful but more importantly did not lock us into a rigid structure like concrete explicit classes. Since we were not yet fully familiar with the language, this flexibility was important; limiting the need for big code refactors when pivots were needed.

  • coming from product and web development projects, json is familiar and works well both in Hoon and in web applications

  • eliminated the need for %mark files; which added unnecessary complexity to the code base for a new development team such as ours

  • gave us the ability to validate our incoming POST requests and provide more robust error handling; such as those needed when writing REST APIs that depend on json as inputs. We found when using mark files, error handling was difficult; often times having code crash deep in the bowels of Urbit when mark/json was invalid. This made it difficult to find the root of the problem, and more importantly made it difficult to gracefully handle errors by providing callers with error information with enough context to fix errors themselves.

Even though Ballot does make heavy use of json, there are a few concrete data types and/or structures that have been defined to carry out function.

plugin.hoon and ballot.hoon can both be found in the <desk>/sur folder of your ship. Descriptions of the types found within these files are described below.

plugin.hoon

call-context - not currently used. may be used in future versions.

action-result - all custom action handlers are required to return action-result objects. the calling driver attempts to cast custom action return values to values of this type. If this type is not returned by the handler, the agent will crash.

+$  action-result
        ::  %.n if the custom action handler failed; otherwise %.y
    $:  success=?
        :: contains error data when success is %.n; otherwise contains response data data
        data=json
        ::  currently unused. may be used in future versions.
        store=json
        ::  any effects (poke, gift, etc...) that should be delivered when the
        ::  handler completes
        effects=(list card:agent:gall)
    ==

ballot.hoon

signature - used when signing votes and or delegating votes. signatures allow us to ensure the integrity of the voting process.

state-1 - v0.0.5 Ballot state

This type contains a reference to all of the various stores supported by the Ballot app. For the sake of coding robust custom actions, you may need to access some of these sub-stores, specifically: booths, proposals, participants listed below:

Booths

key/value pair of booth key -> booth detail data (hoon json)

key
value

booth-key (provided in context)

json

Booths Data - Spec

The booth value (json) is as follows:

Booth Data - Sample

Proposals

map of booth (key) -> proposal (key) -> proposal detail

With a booth-key, you can obtain a dictionary (map @t json) of proposals where each key in the dictionary is a proposal-key.

Proposal Hoon - Spec

Proposal Hoon - Sample

Participants

map of booth (key) -> participant (key) -> participant detail

Participant Hoon - Spec

Participant Hoon - Sample

PreviousSetupNextError Handling

Last updated