Overview
Blockchain technologies allow you to record files and create a single registry that is not owned by one particular owner. This is a database that is distributed among different owners, and it is impossible to record in the middle of the chain. If you record in Blockchain, then it remains there forever. This is very useful, for example, in order to make a single register of property owners. That is, you can make sure that you have exactly the file that was placed in the backup, say, five years ago. In order to make sure that this is so, use mathematical algorithms.
The platform is a document-saving platform with integrated blockchain technology. Hyperledger Fabric technology will be used to create blockchain in a project. Main features:
- BFTC (Byzantine Fault Tolerant Consensus)
- has no cryptocurrency and doesn’t require mining -> no expensive transactions
- private/permissioned network
- transactions can be confidential
- Smart contracts (chain code) run in docker containers -> would be faster than EVM
- Membership Service, instead of traditional wallets that provides credentials to clients and peers for them to participate (clients use this credential to authenticate their transactions)
For the first version, it is decided to make a private/ permissioned blockchain with the following criteria:
- requires an invitation and (or) validation by a network administrator or some set of rules
- different types of access mechanisms
- ability to manage the privacy of transactions
How to Create a Functional Specification Document
A functional specification document (FSD) defines requirements and key features for a blockchain-based document-sharing platform. Here’s how to create an effective FSD:
1. Define Purpose and Scope
Clearly state the goal of the platform. Emphasize security and immutability. Specify document types, users, and permissions in the template.
2. Identify Stakeholders
For example, list business owners, developers, legal teams, and end-users, defining their roles and responsibilities.
3. Establish System Requirements
This includes functional and non-functional requirements:
Functional Requirements:
- User Authentication & Access Control: Define registration, authentication, and permissions.
- Document Storage & Encryption: Specify on-chain, off-chain, or hybrid storage and encryption.
- Smart Contracts: Outline verification, access control, and transaction execution.
- Audit Trail & Immutability: Explain ledger tracking of document changes.
- Collaboration & Versioning: Define editing, commenting, and version control.
Non-Functional Requirements:
- Scalability: Plan for increasing usage.
- Security: Detail encryption, identity verification, and fraud prevention.
- Compliance: Ensure adherence to GDPR, HIPAA, etc.
4. Define User Roles
Categorize admins, document owners, and viewers. Specify their permissions using role-based access control (RBAC).
5. Design User Flow
Illustrate steps for uploading, sharing, and verifying documents with flowcharts or wireframes.
6. Specify Technology Stack
List blockchain network (Ethereum, Hyperledger), consensus mechanism (PoW, PoS), and supporting tools (IPFS, React, Node.js).
7. Define API & Smart Contracts
Detail API calls, smart contract functions, and data structures for seamless integration.
8. Testing & Validation
Specify unit tests and performance benchmarks. Conduct security audits.
Common Challenges in Writing Functional Specifications
Writing a functional specification document comes with several challenges that can impact execution. Here are some common difficulties:
1. Ambiguous Requirements
Vague or incomplete requirements can lead to misunderstandings. They may cause scope creep and misaligned expectations. To avoid this, define requirements clearly. Use precise language, examples, and diagrams in the functional specification template.
2. Lack of Stakeholder Alignment
Developers and business stakeholders may have different expectations. Regular meetings and shared documentation help align them before finalizing specifications.
3. Overcomplicating the Document
Excessive technical jargon or unnecessary details can make the FSD hard to follow. Keep it concise, structured, and focused on essential functionalities while providing references for deeper insights.
4. Ignoring Edge Cases
Failing to consider all potential user scenarios, errors, or security vulnerabilities can lead to unexpected issues post-development. Incorporate a section for exception handling and validation rules.
5. Lack of Scalability Considerations
Not accounting for future growth may require costly rework later. Ensure the document addresses performance, modularity, and future expansion needs.
6. Poor Version Control
Frequent updates to specifications without proper tracking can lead to inconsistencies. Use version control systems or collaborative platforms to track changes. It will help maintain a single source of truth.
7. Inadequate Testing Criteria
An FSD should define clear test cases and success metrics. Without these, validating functionality becomes difficult. Include test scenarios and acceptance criteria for each feature.
8. Failure to Consider Compliance and Security
Neglecting legal or security requirements can delay deployment. Overlooking regulations can lead to compliance violations. Ensure the document includes encryption methods, access controls, and applicable industry regulations.
9. Not Updating the Document Post-Development
An FSD is not a one-time effort—it should evolve with the project. Gather feedback and implementation changes. Regular updates will keep your FSD relevant.
By following best practices, teams can create a robust and actionable functional specification document. It will ensure project alignment and smooth execution.
Why Functional Specification is Important for Blockchain Projects
A functional specification document ensures alignment and efficiency throughout the blockchain project lifecycle. Here’s why it’s essential:
1. Clear Vision and Objectives
Blockchain projects involve complex architectures and various stakeholders. A functional specification template provides a well-defined scope. It helps developers and business teams stay aligned on goals and functionalities.
2. Improved Collaboration and Communication
An FSD serves as a single source of truth, eliminating miscommunication between teams. Developers, designers, and business analysts can reference the document to ensure consistency in execution.
3. Efficient Development Process
With functional specification benefits, developers can work more efficiently, reducing ambiguities and rework. It provides a roadmap for feature implementation, security protocols, and performance requirements.
4. Risk Mitigation and Compliance
Blockchain projects often involve regulatory requirements, smart contract security, and data protection measures. An FSD outlines compliance guidelines, ensuring you adhere to legal and security best practices from the start.
5. Cost and Time Management
Undefined requirements can lead to delays and budget overruns. A functional specification helps control costs by preventing unnecessary changes and ensuring proper resource allocation.
6. Better Testing and Validation
A comprehensive FSD includes test cases and expected outcomes, making it easier to validate blockchain transactions, smart contract functionality, and data integrity before deployment.
7. Scalability and Future Enhancements
Blockchain solutions need to be scalable to support growth. A well-documented FSD ensures that the architecture is flexible, allowing for future upgrades and integrations without major redesigns.
8. Investor and Stakeholder Confidence
Investors and stakeholders need assurance that a blockchain project is well-planned and viable. A detailed FSD demonstrates professionalism, reducing uncertainties and attracting potential funding.
By creating a robust functional specification document, blockchain projects can achieve streamlined development, enhanced security, and long-term success.
Blockchain Project Architecture
In Scope
- User account creation and management, including passwords, will be performed by an administrator from the admin panel
- All uploaded documents will be encrypted by using blockchain technology
- Users should have registered phone numbers in the system to add two steps of authentication in order to improve system security
- The site data must be secure from external sources, e.g., HTTPS and data encryption protocols
- The website must be responsive to be viewable on multiple devices
Functional Risks
- The user may forget a password or change the phone number; in this case, it is presumed that the user will contact the administrator to change the phone number in a system.
- Logged-in Users will be able to access restricted parts of the site, changing fundamental aspects of the site or introducing malware, leading to misrepresentation.
- Site visitors (not logged in) will be able to access sections of the site reserved for logged-in users, reducing the credibility of the site.
- Users will not be able to access the site on mobile devices, reducing the overall impact of the site.
Use Cases, Admin
- Registration in the project
- A user loads a blockchain project for the first time on a desktop, tablet or mobile through a browser
- Administrator's first login
- Create user screen
- Import users
- List of users
- The Admin creates the first Safe Chain
- The Admin checks added steps
- The Admin edits steps of the chain
- View the thread for one chain
- Admin dashboard
Use Case 1 - Registration in the project
All admin accounts are registered by the product owner; for admin registration, the necessary fields are:
- Name (first and last)
- Phone number
All user accounts can be registered by admin or imported to the project by admin and will have the following details:
- Name (first and last)
- Phone number
Use Case 2 - A user or Admin loads Safe Chain for the first time on a desktop, tablet or mobile through a browser
Login Page
- The header will have the logo of SafeChain and two fields:
- Enter your email
- Enter your password
- Button login
Actions:
The Admin or user adds email login provided and password related (all admin access credentials will be created from server side by the product owner, admin may register authorized users); after adding these data and pressing login, user will see “Enter SMS code fields” also user will receive SMS with code to the phone number that is registered and verified. SMS includes code, which the user adds into an additional field to confirm identity.
Possible issues:
The SMS code could not work in case the external service had a technical issue, or the user added the wrong digits.
Use Case 3 - Administrator's first login
When the Admin logins to the system for the first time, there are no records for Safe Chains and no records for users available in the system.
An Admin sees the following:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Side menu with the following sections:
- My SafeChains
- List of users
- Safechain log
- Create a user button
- “Create new chain” button
Actions:
An Admin should start with creating or importing users. The Admin presses the Add user button and leads to the proper section.
Use Case 4 - Create a user screen
Create a user screen consisting of the following:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Side menu with the following:
- My safechains
- List of Users
- Cancel button
- New user section:
○ Obligatory fields:
■ First and last name
■ Email
■ Phone number
○ Optional fields
■ Company name
■ Description
- Checkbox “This user is an Admin.”
- Import users button
- Save button
Actions:
Admin should fill out all mandatory fields to save new users; if one of the mandatory fields is not added, the Save button will not be active to save changes. Mandatory fields are needed for further 2-factor authentification of users and other admins created.
Optional fields will help identify users and describe them.
If Admin presses the checkbox “Admin”, the role Admin should be added to a newly created user. Pressing the import user's button will lead to proper functionality.
After saving the result, the Admin will forward it to the List of Users screen.
Use Case 5 - Import users
By pressing the “Import users button”, the admin will see a pop-up which allows them to choose an xls file with presumed structure to upload a list of users. In the document, there will be the same mandatory and optional fields.
Error handling: If the file is not set correctly, the Admin should get the notification that the file has errors and cannot be processed.
Use Case 6 - List of users; Admin may manage users inside this section
The list of users screen consists of the following:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Side menu with the following:
- My SafeChains
- List of Users
- Safechain log
- Create user button
- Exact list of users with status:
- First name
- Last name
- Role
It would be good to add filters to sort users alphabetically, ASC/DESC, by date of creation.
- Edit user section:
○ Obligatory fields:
■ First and last name
■ Email
■ Phone number
○ Optional fields
■ Company name
■ Description
- Checkbox “Admin.”
- Import users button
- Export users button
- Save button
- Cancel button
Possible issues:
When the administrator clicks the Save button, fields that are set incorrectly or are missing Obligatory fields should be highlighted in red.
Delete user flow:
When Admin clicks on delete user, he will see a popup confirmation with the text “Are you sure you want to delete this user?” and Buttons ‘Delete’ and ‘No’.
Use Case 7 - The Admin is inside the system and creates the first SafeChain with the first step
By pressing on the ‘Create SafeChain’ button, the Admin sees the ‘Create your Safe chain’ page with the following fields:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Safechain name
- Step name - text fields
- Documents - with the option to upload a file
○ Required checkmark
- Invite users to view or upload documents - with a drop-down to choose users
- Read checkmark
- Write checkmark
- Invite users to validate documents
○ Required checkmark
‘Save new step’ button
Cancel button
Actions:
Admin should add all fields and set settings for the step to save new SafeChain with the first step.
Possible issues:
When the administrator clicks the Save New Step button, fields that are set incorrectly or are missing Obligatory fields should be highlighted in red.
Example of the filled-out form:
Use Case 8 - The Admin checks added steps
Added steps screen consists of:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Slide menu with the following sections
- List of users
- My SafeChains
- Safechain log
- Create user button
- View threads button
- Name of exact Safachain chosen
- Setting steps and users to a chain part
- Status of each step
- List of steps
- Documents required
- Users invited
- Add a new step button
- Save button
Actions:
Add New Step button will lead to the Add New Chain Step functionality. By pressing the particular step admin may edit it.
Admin may edit each step of the chain by pressing the edit button.
Use Case 9 - The Admin edits steps
If Admin presses the edit button for a step of a Chain, Edit step for a chain screen appears, which consists of the following:
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- Side menu
- View thread button
- Step name - text field
- New document category field
- Documents - with the option to set the number from and to
- Edit users to view or upload documents - with a drop-down to choose users
- Read checkmark
- Write checkmark
- Add user button
- Edit users to validate documents
- Required checkmark
- Add user button
- Save button
Actions:
Admin may open and check the thread for the step of the chain. At this screen, Admin may:
- Add a new type of document (in v1, it is presumed to have two types of documents: Certificates and Photos).
- Pressing the view thread button opens the view thread screen and sets the number of documents that are allowed to be in this step of the chain.
- By pressing the Save button, the Admin will be directed to the created steps screen.
Use Case 10 - View the threads for one chain
Consists of:
- Safechain logo
- Top menu with the following:
○ Notifications
○ Settings
○ Name of Admin who works in a system
○ Logout - Side menu
- Thread for the particular chain created, including:
- Reference number
- Date
- Documents
- Save button
Actions:
The thread will be created automatically when a new chain is created by Admin at the backend.
Use Case 11 - Admin dashboard
My Safechains for admin
- Admin = logged in
- Safechain logo
- Top menu with the following:
- Notifications
- Settings
- Name of Admin who works in a system
- Logout
- The sidebar will have 4 sections.
○ My Safechains
○ List of users
○ Safechain log
○ Add a user button - The main section will consist of a list of Safechains as a leader section and Safechain as a participant section, with the button “Create new chain” at the top.
Actions:
- By pressing My Safechains, admin stays in the same section.
- By clicking the “List of users” section, the Admin will see the List of Users page.
- By clicking the add user button, Admin will be forwarded to the section where it may create a user or import a list of users.
- By pressing the name of the particular Safe Chain, the admin will see its details.
- By clicking Create new chain, the user will be forwarded to the Create new chain screen.
- When the admin presses one of the names of Safe Chains as a leader, the admin will see "Edit the steps screen".
User Flow
Use Cases
12. The login procedure for the user
13. The User checks Safechain(s)
14. Details of user’s Safe chain
15. Document’s review
Use Case 12 - The login procedure for the user
Action
To get into the system, the user will need to go through the same procedure as the Administrator process. The user adds the email login provided and password related (all admin access credentials will be created from the server side by the product owner, admin may register authorized users). After adding these data and pressing login, the user will see “Enter SMS code fields”. Also, the user will receive an SMS to the phone number that is registered and confirmed. SMS includes code, which the user adds into an additional field to confirm identity.
Possible issues
The SMS code could not work in case the external service has a technical issue or the user adds the wrong digits.
Possible scenario
Adding the Contact Administrator button to report an issue.
Use Case 13 - The User checks My Safechain(s)
The User checks My Safechain(s)
- User = logged in
- Safechain logo
- Top menu with the following:
○ Name of User who works in a system
● The sidebar with 2 sections.
○ My SafeChains
○ SafeChain log
Under My Safechains, the user will see a list of chains where the user is involved, and new safe chains will be marked; by pressing on the exact Safechain name, the user will see if the correct side documents were assigned to the Safechain and buttons Approve/Decline.
If the user presses the Approve button, documents go to the next stage; if the user presses the Decline button, an additional text field appears for an explanation of why the document will be declined.
Example of the document to Approve or Decline
Users see the following buttons:
- Decline, by pressing this button, the user will see a pop-up where it is necessary to add an explanation of why the document is cancelled; after pressing Proceed, the user will be forwarded to the previous screen, and the document will be marked as cancelled.
- Accept; by pressing this button, the user will confirm the document, and it will go to the next step of the chain for further confirmation.
- Download (if the user has permission to download the file).
- Close the window button.
Example of approved and cancelled documents.
Use Case 14 - logs
Logs
- 2. User = logged in
- Top menu with the following:
○ Name of User who works in a system
- The sidebar will have 2 sections:
- My Safechains
- Safechain log
- The main section will consist of a list of Safechains that users already participate in.
Actions:
● by pressing My Safechains, the user stays in the same section
● by clicking “Safechain log”, the user will see a log related to the safe chain where the user has been added as a participant
● in case the user has just one safe chain, a log for this particular safe chain will be shown only
● in case the user has few safechains, that screen will be divided into two parts, and the left part will show a list of Safechains
● by pressing the name of the particular Safe Chain, the user will see details of it.
View several Safechains logs in the user’s account.
Page List for User
The following is the list of user-facing pages that are anticipated for the site. Administrator pages are not listed below. Static textual content for the page is also provided where needed.
SMS Notifications to the User
To limit the scope of email notifications in Step 1, you can consider one summary email notification per user, as shown below. Administrator email notifications are not covered in this section.
Technology solution:
Blockchain solution: Hyperledger Fabric
Chain code (smart contracts) language: Go / Java
Blockchain type - Private
File storage: BigchainDB
Cloud server solution: Amazon AWS
Standalone Solution for companies with Government restrictions
CI/CD solution: Jenkins
Backend: Python, Django, PostgreSQL, RadisDB
Frontend: Angular 4 / React
Base secure level:
All nodes are installed inside the company
Improved secure level:
Several nodes are installed for each company/blockchain user.
Subscribe
Thank you!
Get ready! You will receive handpicked content right to your inbox.