claimant

Documentation

Overview

Package claimant is a code model for the Claimant Model.

Index

• Variables
• type Claim
• type Model
  • func LogModelForDomain(m Model) Model
  • func (m Model) BelieverMarkdown() string
  • func (m Model) ClaimMarkdown() string
  • func (m Model) ClaimTerms() []string
  • func (m Model) Markdown() string
  • func (m Model) Questionnaire() string
  • func (m Model) VerifierList() map[string]string
  • func (m Model) VerifierMarkdown() string
• type Models
  • func (ms Models) Actors() []string
  • func (ms Models) Markdown() string
  • func (ms Models) SequenceDiagram() string

Variables

var (
	// TemplateModelMarkdown is the markdown template for a model.
	//go:embed tmpl_model.md
	TemplateModelMarkdown []byte

	// TemplateQuestionsMarkdown is the markdown template for a model questionnaire.
	//go:embed tmpl_questions.md
	TemplateQuestionsMarkdown []byte

	// TemplateSequenceMarkdown is the markdown template for the sequence diagram.
	//go:embed tmpl_sequence.md
	TemplateSequenceMarkdown []byte
)

Types

type Claim

type Claim struct {
	// Claim is a falsifiable statement, e.g. "The number 7 is prime"
	Claim string `yaml:"Claim"`
	// Verifier is an actor that can verify the claim, e.g. "Primal Calculator"
	Verifier string `yaml:"Verifier"`
}

Claim represents a falsifiable statement along with an actor that can verify it.

type Model

type Model struct {
	// System is a short upper case name that models the essence of this model, e.g. "FIRMWARE".
	System string `yaml:"System"`
	// Claimant is the actor playing the role of the Claimant.
	Claimant string `yaml:"Claimant"`
	// Statement is the concrete type that the Claimant issues, and is likely the thing that is logged.
	Statement string `yaml:"Statement"`

	// Believer is the actor playing the role of the Believer.
	Believer string `yaml:"Believer,omitempty"`
	// Believers are the actor playing the roles of the Believer.
	// This should only be provided if there are multiple Believers, and if
	// provided then Believer should be left empty.
	Believers []string `yaml:"Believers,omitempty"`

	// Claim is the claim made by the Claimant.
	Claim Claim `yaml:"Claim,omitempty"`
	// Claims are the claims made by the Claimant.
	// This should only be provided if there are multiple Claims, and if
	// provided then Claim should be left empty.
	Claims []Claim `yaml:"Claims,omitempty"`

	// Arbiter is the actor or process that fulfills the Arbiter role.
	Arbiter string `yaml:"Arbiter"`
}

Model represents a Claimant Model, mapping the roles to actors. See https://github.com/google/trillian/blob/master/docs/claimantmodel/CoreModel.md for descriptions of these roles. Repeating the definitions here will only lead to stale documentation.

func LogModelForDomain

func LogModelForDomain(m Model) Model

LogModelForDomain proposes a template Claimant Model for human editing based on a domain model provided.

func (Model) BelieverMarkdown

func (m Model) BelieverMarkdown() string

BelieverMarkdown renders the Believer(s) in markdown.

func (Model) ClaimMarkdown

func (m Model) ClaimMarkdown() string

ClaimMarkdown renders the Claim(s) in markdown.

func (Model) ClaimTerms

func (m Model) ClaimTerms() []string

ClaimTerms finds all of the terms used in the Claim that must be present in the Statement.

func (Model) Markdown

func (m Model) Markdown() string

Markdown returns this Claimant Model in a definition table that renders clearly in markdown format.

func (Model) Questionnaire

func (m Model) Questionnaire() string

Questionnaire returns some questions to guide the designer to ensure that the claimant model is sound.

func (Model) VerifierList

func (m Model) VerifierList() map[string]string

VerifierList returns all of the verifiers mapped to the claim they verify.

func (Model) VerifierMarkdown

func (m Model) VerifierMarkdown() string

VerifierMarkdown renders the Verifier(s) in markdown.

type Models

type Models struct {
	Domain Model `yaml:"Domain"`
	Log    Model `yaml:"Log"`
}

Models captures the domain model along with the log model that supports it. This can be extended for more general model composition in the future, but this is the most common composition and motiviation for Claimant Modelling.

func (Models) Actors

func (ms Models) Actors() []string

Actors returns all of the actors that participate in the ecosystem of logging the domain claims and verifying all behaviours.

func (Models) Markdown

func (ms Models) Markdown() string

Markdown returns the markdown representation of both models.

func (Models) SequenceDiagram

func (ms Models) SequenceDiagram() string

SequenceDiagram returns a mermaid markdown snippet that shows the idealized workflow for this log ecosystem. This can be changed in the future to support other variations in the workflow, e.g. this generates a sequence that shows the claimant awaiting an inclusion proof and then creating an offline bundle, but not all ecosystems do this and so perhaps this should take some kind of Options that allows these cases to vary. For now, this is out of scope and this generated sequence diagram should be taken to represent the current best practice, and designers can modify it to reflect the deltas in their world.