idOS Storage Network
Last updated
Last updated
User data in idOS is stored the idOS Storage Network, a decentralized layer 1 blockchain secured and run by the idOS Operators to ensure data privacy, security, and availability.
An idOS Storage Network Node consists of five core components:
Authentication protocol – Users authenticate using cryptographic keys (e.g. Ethereum, NEAR, XRPL or other wallets), ensuring self-sovereign control over their data.
Consensus protocol – All modifications to the relational database require distributed agreement among participating nodes, ensuring data integrity and resistance to unauthorized changes.
Relational Database – Instead of storing identity data as flat files or documents, idOS uses a structured relational model, making it possible to query and manage user data efficiently.
Encryption and Signing Libraries - idOS nodes have several key cryptographic libraries used for various encryption, signing and hashing operations.
RPC load balancer gateway — Ensures that only authorized node operators are included in the RPC server pool. Currently only the idOS Association's node is authorized to run the RPC gateway, as we further decentralize the network this will change. The domain for this gateway is:
In future updates, we will be introducing Native Modules for additional network functionality, starting with TSS-powered key abstraction for seamless cross-device encryption and biometrics for secure, private biometric authentication.
Nodes are implemented in Go and distributed as blah blah, and are source available here. Initially, all nodes are run by the idOS Association, with a plan to open it up in the near future. Nodes can be run on any device with sufficient compute and storage (link?), but we expect most providers to run their nodes in public clouds or using rented data center capacity.
User: The central identity entity in the system, representing a unique person or organization. Users control their profiles through their blockchain wallets and manage how their data is shared.
User Profile: This is an informal, nebulous, term to refer generally to all the information a user controls.
Wallet: Blockchain wallets that authenticate a user. A user can link multiple wallets across different chains (EVM, NEAR) to their idOS profile to provide flexible authentication options.
Credential: Verified claims or attestations about a user. Notable fields are:
User: The individual to whom this credential was issued and whose information the credential verifies.
Public Notes: Readable metadata that is visible to any platform where the user logs in to idOS. Issuers can update these notes, for example, to reflect the credential's revocation status.
Encrypted Content: The credential's core data, securely encrypted so that only the user and explicitly authorized parties can access it.
Issuer Address: The public key of the issuer's signer, which issued and signed the credential to ensure its authenticity and integrity.
An unintuitive aspect of credentials is that they're encrypted specifically for one recipient. To share credential data, the user (or their authorized delegate) must retrieve their encrypted credential, decrypt it using their keys, re-encrypt it for the new recipient, and store this as a new credential that references the original using SharedCredential. This process ensures end-to-end encryption while enabling controlled sharing.
Because credential content data arrives at idOS already encrypted, it cannot enforce any structure to it. However, we strongly encourage Issuers to use W3C Verifiable Credentials, and provide functionality to support them.
Access Grant: A user-authorized permission that allows a specific Consumer to access a credential's encrypted content:
Owner: The user who issued the grant
Data ID: ID of the specific credential being shared
Consumer Address: The recipient's address authorized to access the data
Timelock: An optional lock date before which the access grant can't be revoked. Useful for some compliance scenarios.
Attributes: Additional public (to applications where the user logs in to idOS) key-value pairs associated with a user profile, providing configurable metadata.
While Issuers and Consumers are key actors in the system, they are primarily represented by their blockchain addresses, rather than as separate entity types in the data model.
Account Creators: A designated set of trusted Issuers that have permission to create new idOS User profiles. This concept will be phased out after we deploy and mature the idOS Economy.
Delegated Write Grants: A Delegated Write Grant (dWG) is a mechanism that allows a user to delegate powers for a specific issuer to create a credential, its copy, and an access grant on behalf of a user. This is particularly useful for scenarios where the user does not need to revisit the issuer's platform for it to add data to their profile.
A dWG is implemented as a message signed by the user. The message includes the following fields:
Operation: Specifies the operation type, always being delegatedWriteGrant.
Owner: The user's wallet identifier.
Consumer: The consumer's wallet identifier.
Issuer Public Key: The issuer's Ed25519 public key (hex-encoded).
ID: A unique identifier for the dWG.
Access Grant Timelock: A timestamp (RFC3339 format) indicating until when the access grant will be locked.
Not Usable Before: A timestamp (RFC3339 format) indicating when the dWG becomes valid.
Not Usable After: A timestamp (RFC3339 format) indicating when the dWG expires.
Whoever transmits the dWG to idOS also needs to provide the original and copy credentials' fields (including the encrypted content). Check the schema for more details.
dWGs can only be used once.
Delegated Access Grants:
Delegated Access Grants (dAGs) are a mechanism that allows entities other than the user to create Access Grants on their behalf.
A dAG is implemented as a signed message containing the following fields:
Data ID: The identifier of the credential or data being shared.
Owner Wallet Identifier: The wallet address of the user who owns the data.
Grantee Wallet Identifier: The wallet address of the entity receiving access.
Signature: A cryptographic signature verifying the authenticity of the dAG.
Locked Until: A timestamp indicating when the Access Grant can be revoked.
Content Hash: A hash of the data being shared to ensure integrity during Passporting.
Whoever transmits the dAG to idOS also needs to provide the copy credential's fields (including the encrypted content). Check the schema for more details.
dAGs can be used multiple times.
🚧 Will change soon 🚧
dAG being multi-use is a remnant of the previous Access Grant architecture. Given how the usefulness of dAGs has been evolving, we're going to make them single-use.
If you want to rely on multi-use, please get in touch with us first, so we can properly guide you and evolve the system accordingly.
The idOS access management protocol defines how access rights to user data are managed, ensuring that all requests are both authenticated and authorized before any data is shared. This protocol governs who has permission to access data stored in idOS, providing a structured and secure method for managing personal information while maintaining user control.
To grant access, users must first authenticate themselves, proving that they own the relevant identity and data. Authentication answers the question, “Who are you?” and is performed through a cryptographic wallet signature. This step ensures that only legitimate users can interact with idOS nodes. To protect against replay attacks, every authentication request includes an incrementing nonce, ensuring that past authentication signatures cannot be reused maliciously.
Beyond authentication, all queries must be authorized to determine “What can you do?”. Authorization works by verifying the wallet signature and recovering the associated address, which is then injected into structured queries. This mechanism ensures that only those with legitimate permissions can perform actions on stored data, preventing unauthorized access and modification.
Once authentication and authorization are confirmed, users can grant access to their data to third parties, such as neobank apps, regulated financial modules or other individuals and entities. If access is requested through an app, the idOS SDK simplifies the process by automatically inserting the correct recipient’s wallet address. If the user grants access manually via the idOS Dashboard, they must input the recipient’s details themselves.
In both cases, the process remains secure and private: the user decrypts their own data, re-encrypts it using the recipient’s public key, and then uploads the encrypted data back to the idOS network. This ensures that only the intended recipient can access the data, preventing unauthorized parties from intercepting or decrypting it.
(Delegated) Access Grants
An Access Grant gives an idOS Consumer access to one credential within and idOS User Profile. Access Grants can be revoked by the user at anytime, unless they were associated with a regulatory time-lock during the time of issuance.
(Delegated) Write Grants
A Write Grant gives an idOS Issuer the ability to issue exactly one credential into a idOS User Profile. In addition to adding the credential, the Issuer also has the option to provide additional Access Grants to themselves or are 3rd party. This information is conveyed to the User before signing a Write Grant.
Delegated Version: Permits an authorized recipient to grant limited and controlled access to third parties on behalf of the original user by signing a message.
A major advantage of the idOS access management system is that data remains continuously available, even if the original user is offline. Once an access grant has been issued, the recipient can retrieve the authorized data at any time, provided that the grant remains active. This eliminates reliance on user availability and allows businesses and services to securely access user data without requiring permanent downloads or redundant storage.
This persistent availability enables organizations to use the idOS as a decentralized, privacy-preserving customer relationship management (CRM) tool for verified users. Businesses and service providers can access user data on demand, maintaining a live and up-to-date identity verification process without storing unnecessary copies of user data, reducing compliance risks.
At any time, users retain full control over their data and can revoke access, immediately disabling the recipient’s ability to retrieve or decrypt the information. If a data recipient no longer requires access, or if a user changes their mind, revocation ensures that data permissions are always dynamic and adjustable.
For cases where regulatory compliance requires specific retention periods, access grants can be time-locked, ensuring that data remains accessible for a predefined duration before revocation is possible. For example, a financial institution may require a five-year data retention period due to compliance regulations. In such cases, revocation will only be possible once the time lock expires, ensuring compliance with data governance policies.
Compliance with GDPR’s Right to Be Forgotten – Unlike traditional immutable blockchain-based storage, Kwil-powered decentralized storage on idOS enables us to operate with a limited history of nodes. This allows us to ensure that data deletion requests don't simply unincentivize the storage of data or change state on a public blockchain transparently, but that they truly and verifiably delete data from all idOS nodes, giving idOS the ability to comply with right-to-be-forgotten privacy laws like GDPR.
Custom Authenticators: Kwil was designed to support any type of authenticators, as long as they're deterministic and self-contained. This enables us to quickly become compatible with chains that decided to have their own signing schemes. We currently have support for EVM (secp256k1) and NEAR (ed25519), and adding a new one is a matter of a handful of engineering hours.
TODO
The Kwil GateWay (KGW) is a load balancer and RPC gateway that sits in front of all idOS Storage Network Nodes. It also holds access cookies, which make it possible for logged in users to not have to sign every read request to the nodes. Right now only the idOS Association is able to run a gateway, we will add the ability for idOS Operators and others to run their own in the future.
Relevant repos:
Currently, all idOS nodes are operated by the idOS Association, ensuring stability and security in the early stages. However, we are actively onboarding new node operators in H2 2025, with a long-term goal of fully decentralizing the network. Initially the network will run an auction for 20 operator slots, and all operators will be KYB'd by the idOS Association.
If you are interested in running a node and contributing to the privacy-preserving identity ecosystem, reach out to us to learn more about technical requirements and incentives for operators.
The idOS Storage Network utilizes , a decentralized relational database, for storing and managing identity data, and each idOS node run a customized implementation of Kwil's storage and consensus. This design enables key features for idOS as a decentralized personal identity cloud:
Cooperation-oriented consensus mechanism: Because not all specialized networks need fully permissionless validator sets (idOS Association will KYB all idOS Operators for the forseeable future), our consensus mechanism, Kwil's , is tailored towards validator sets that are selected by governance mechanisms, shedding overhead that traditional blockchain BFT algorithms require. It's inspired by both CometBFT and more classical distributed system consensus algorithms, taking the best from both and tailoring it for personal storage use cases like identity.
(🚧 not yet public 🚧): idOS's kgw Docker image
