ic_certified_blockchain.did

type Block = record {
  // Certificate is signed by the NNS root key and contains the root of tree.
  certificate: blob;
  // Under b"certified_blocks is a map from i as u32 BE bytes to sha256(sha256(caller{i])sha256(data[i]))
  // with an entry from "previous_hash" to previous_hash.
  tree: blob;
  // The raw data entries.
  data: vec blob;
  // Callers of prepare()/prepare_some() for corresponding "data".
  callers: vec principal;
  previous_hash: blob;
};

type Auth = variant { User; Admin };
type Authorization = record {
  id: principal;
  auth: Auth;
};

service blockchain: (opt text) -> {
  // Stage a block, returning the certified data for informational purposes.
  // Traps if some data is already staged.
  prepare: (data: vec blob) -> (blob);
  // Stage some (more) data into a block, returning the hash of the root of tree for informational purposes.
  prepare_some: (data: vec blob) -> (blob);
  // Get certificate for the certified data. Returns None if nothing is staged.
  get_certificate: () -> (opt blob) query;
  // Append the staged data with certificate and tree.  Traps if the certificate is stale.
  // Returns None if there is nothing staged.
  commit: (certificate: blob) -> (opt nat64);
  // Get a certified block.
  get_block: (index: nat64) -> (Block) query;
  // Find block index with matching block hash or latest matching data entry hash.
  find: (hash: blob) -> (opt nat64) query;
  // Return the index of the first block stored.
  first: () -> (nat64) query;
  // Return the index of the start of the primary part (length of log - first() - secondary.len()).
  mid: () -> (nat64) query;
  // Return the index of the next block to be stored (the length of the log - first()).
  next: () -> (nat64) query;
  // Return hex string representing the hash of the last block or 0.
  last_hash: () -> (text) query;
  // Rotate the log by making the primary part secondary and deleting the old secondary and making it primary.
  // Returns the new first index stored if the secondary part had anything to delete.
  rotate: () -> (opt nat64);
  // Manage the set of Principals allowed to prepare and append (User) or authorize (Admin).
  authorize: (principal, Auth) -> ();
  deauthorize: (principal) -> ();
  get_authorized: () -> (vec Authorization) query;
}