The Lifecycle and Roles of Documents

This page documents the ObjectID document workflow as implemented in the Move contract. It explains the state transitions, who can perform them, and how editors, approvers, publisher, and creator interact during the lifecycle.

Overview

An OIDDocument starts in DRAFT. From there it can move to APPROVAL_PENDING, then to APPROVED, then to RELEASED, and finally to REVOKED. The contract also tracks editors, approvers, a publisher DID, and a change log.

Initial Setup at Creation

When the document is created, the creator DID is automatically assigned as:

  • the creator
  • the first editor
  • the first approver
  • the default publisher

The initial status is DRAFT. The initial approval flag for the default approver is NOT_APPROVED.

States

  • DRAFT: working state. Editors can still update the document hash, URL, and mutable metadata.
  • APPROVAL_PENDING: the document is waiting for approvers to review and vote.
  • APPROVED: all approvers have their approval flag set to APPROVED.
  • RELEASED: the publisher has formally released the document.
  • REVOKED: the creator has revoked a previously released document.

Lifecycle

1. Draft

In DRAFT, authorized editors can update:

  • document hash
  • document URL
  • mutable metadata

The combined update of hash and URL is explicitly restricted to DRAFT. Editors can also move the document from DRAFT to APPROVAL_PENDING.

2. Approval Pending

In APPROVAL_PENDING, each approver can set only their own approval flag to either:

  • NOT_APPROVED
  • APPROVED

If at least one approver remains NOT_APPROVED, the document stays in APPROVAL_PENDING. If all approvers are APPROVED, the contract automatically changes the document status to APPROVED.

Editors are also allowed to move the document from APPROVAL_PENDING back to DRAFT.

3. Approved

APPROVED means every approver currently registered on the document has approved it. This status is not set manually by an editor or publisher. It is reached automatically when the last pending approval becomes APPROVED.

If an approver later changes their own flag back to NOT_APPROVED, the contract automatically moves the document back from APPROVED to APPROVAL_PENDING.

4. Released

The transition from APPROVED to RELEASED can be executed only by the DID stored in publisher_did. If someone else tries to release the document, the transaction fails.

5. Revoked

The transition from RELEASED to REVOKED can be executed only by the creator_did. The creator is therefore the final authority for revocation.

Allowed Status Transitions

  • DRAFT -> APPROVAL_PENDING: only an editor
  • APPROVAL_PENDING -> DRAFT: only an editor
  • APPROVAL_PENDING -> APPROVED: automatic when all approvers are approved
  • APPROVED -> APPROVAL_PENDING: automatic if any approver switches back to NOT_APPROVED
  • APPROVED -> RELEASED: only the publisher
  • RELEASED -> REVOKED: only the creator

Any other transition is rejected by the contract.

Roles and Permissions

Creator

  • Creates the document
  • Is automatically added as initial editor, approver, and publisher
  • Can add editors
  • Can remove editors
  • Can add approvers
  • Can remove approvers
  • Can update publisher DID
  • Can update owner DID
  • Can delete the document only while it is still in DRAFT
  • Can revoke the document after it has been released

Editor

  • Can update mutable metadata
  • Can update document URL and hash while the document is in DRAFT
  • Can move the document from DRAFT to APPROVAL_PENDING
  • Can move the document from APPROVAL_PENDING back to DRAFT
  • Cannot release the document unless they are also the publisher
  • Cannot manage editor or approver lists unless they are also the creator

Approver

  • Can update only their own approval flag
  • Can set their own state to APPROVED or NOT_APPROVED
  • Can act only when the document is in APPROVAL_PENDING or APPROVED
  • Cannot directly set the document to RELEASED or REVOKED

Publisher

  • Can move the document from APPROVED to RELEASED
  • Cannot release the document if it is not already APPROVED
  • Can be reassigned by the creator through update_publisher_did

Managing Editors and Approvers

Only the creator can change the role lists.

Add a New Editor

  • Function: add_editors_did
  • Caller must be the creator
  • If the DID is not already present, it is appended to editors_dids

Remove an Editor

  • Function: remove_editors_did
  • Caller must be the creator
  • If the DID is present, it is removed from editors_dids

Add a New Approver

  • Function: add_approver_did
  • Caller must be the creator
  • If the DID is not already present, it is appended to approvers_dids
  • A matching NOT_APPROVED flag is also appended to approval_flags

This means any newly added approver must explicitly approve before the document can be considered fully approved.

Remove an Approver

  • Function: remove_approver_did
  • Caller must be the creator
  • If the DID exists, both the approver DID and its matching approval flag are removed at the same index

Important Behavioral Notes

  • The contract consumes document credit for all operational updates, including role changes and status changes.
  • The document maintains a change_log with actor, operation, parameters, and timestamp.
  • The release step is intentionally separated from approval: full approval does not automatically release the document.
  • Revocation is intentionally stricter than release: only the creator can revoke.

Reference Flow

  1. Creator creates the document. Status starts at DRAFT.
  2. Creator may add extra editors and approvers.
  3. An editor updates the hash and URL while still in DRAFT.
  4. An editor moves the document to APPROVAL_PENDING.
  5. Each approver records their own approval.
  6. When all approvers are approved, the contract automatically moves the document to APPROVED.
  7. The publisher moves the document from APPROVED to RELEASED.
  8. The creator can later move the document from RELEASED to REVOKED.