mirror of
https://github.com/onsonr/sonr.git
synced 2025-03-10 13:07:09 +00:00
fix: update devbox lockfile
This commit is contained in:
parent
4a8a15e4d6
commit
93770d481a
1
.gitignore
vendored
1
.gitignore
vendored
@ -13,6 +13,7 @@ dist
|
|||||||
**/.haptic
|
**/.haptic
|
||||||
static
|
static
|
||||||
pkg/webapp/dist
|
pkg/webapp/dist
|
||||||
|
.agent
|
||||||
|
|
||||||
# Test binary
|
# Test binary
|
||||||
*.test
|
*.test
|
||||||
|
54
devbox.lock
54
devbox.lock
@ -144,60 +144,6 @@
|
|||||||
"store_path": "/nix/store/1bnivwijzrnzx5h0hd5rywwy8rlhxmw5-gum-0.14.5"
|
"store_path": "/nix/store/1bnivwijzrnzx5h0hd5rywwy8rlhxmw5-gum-0.14.5"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
|
||||||
"ipfs@latest": {
|
|
||||||
"last_modified": "2023-02-24T09:01:09Z",
|
|
||||||
"resolved": "github:NixOS/nixpkgs/7d0ed7f2e5aea07ab22ccb338d27fbe347ed2f11#ipfs",
|
|
||||||
"source": "devbox-search",
|
|
||||||
"version": "0.17.0"
|
|
||||||
},
|
|
||||||
"templ@latest": {
|
|
||||||
"last_modified": "2024-10-13T23:44:06Z",
|
|
||||||
"resolved": "github:NixOS/nixpkgs/d4f247e89f6e10120f911e2e2d2254a050d0f732#templ",
|
|
||||||
"source": "devbox-search",
|
|
||||||
"version": "0.2.778",
|
|
||||||
"systems": {
|
|
||||||
"aarch64-darwin": {
|
|
||||||
"outputs": [
|
|
||||||
{
|
|
||||||
"name": "out",
|
|
||||||
"path": "/nix/store/n7bmbwk126kiclzi317yprpnc6rkn0jv-templ-0.2.778",
|
|
||||||
"default": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"store_path": "/nix/store/n7bmbwk126kiclzi317yprpnc6rkn0jv-templ-0.2.778"
|
|
||||||
},
|
|
||||||
"aarch64-linux": {
|
|
||||||
"outputs": [
|
|
||||||
{
|
|
||||||
"name": "out",
|
|
||||||
"path": "/nix/store/9fi535j2qw60x28vb5wlcz989z2wz959-templ-0.2.778",
|
|
||||||
"default": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"store_path": "/nix/store/9fi535j2qw60x28vb5wlcz989z2wz959-templ-0.2.778"
|
|
||||||
},
|
|
||||||
"x86_64-darwin": {
|
|
||||||
"outputs": [
|
|
||||||
{
|
|
||||||
"name": "out",
|
|
||||||
"path": "/nix/store/6r17bj68ahbf41xlk87pilbhj394anyy-templ-0.2.778",
|
|
||||||
"default": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"store_path": "/nix/store/6r17bj68ahbf41xlk87pilbhj394anyy-templ-0.2.778"
|
|
||||||
},
|
|
||||||
"x86_64-linux": {
|
|
||||||
"outputs": [
|
|
||||||
{
|
|
||||||
"name": "out",
|
|
||||||
"path": "/nix/store/6c1sqrhl7a68npksq7jicsa310qj9k1q-templ-0.2.778",
|
|
||||||
"default": true
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"store_path": "/nix/store/6c1sqrhl7a68npksq7jicsa310qj9k1q-templ-0.2.778"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -1,141 +0,0 @@
|
|||||||
# `x/did`
|
|
||||||
|
|
||||||
The Decentralized Identity module is responsible for managing native Sonr Accounts, their derived wallets, and associated user identification information.
|
|
||||||
|
|
||||||
## State
|
|
||||||
|
|
||||||
The DID module maintains several key state structures:
|
|
||||||
|
|
||||||
### Controller State
|
|
||||||
|
|
||||||
The Controller state represents a Sonr DWN Vault. It includes:
|
|
||||||
- Unique identifier (number)
|
|
||||||
- DID
|
|
||||||
- Sonr address
|
|
||||||
- Ethereum address
|
|
||||||
- Bitcoin address
|
|
||||||
- Public key
|
|
||||||
- Keyshares pointer
|
|
||||||
- Claimed block
|
|
||||||
- Creation block
|
|
||||||
|
|
||||||
### Assertion State
|
|
||||||
|
|
||||||
The Assertion state includes:
|
|
||||||
- DID
|
|
||||||
- Controller
|
|
||||||
- Subject
|
|
||||||
- Public key
|
|
||||||
- Assertion type
|
|
||||||
- Accumulator (metadata)
|
|
||||||
- Creation block
|
|
||||||
|
|
||||||
### Authentication State
|
|
||||||
|
|
||||||
The Authentication state includes:
|
|
||||||
- DID
|
|
||||||
- Controller
|
|
||||||
- Subject
|
|
||||||
- Public key
|
|
||||||
- Credential ID
|
|
||||||
- Metadata
|
|
||||||
- Creation block
|
|
||||||
|
|
||||||
### Verification State
|
|
||||||
|
|
||||||
The Verification state includes:
|
|
||||||
- DID
|
|
||||||
- Controller
|
|
||||||
- DID method
|
|
||||||
- Issuer
|
|
||||||
- Subject
|
|
||||||
- Public key
|
|
||||||
- Verification type
|
|
||||||
- Metadata
|
|
||||||
- Creation block
|
|
||||||
|
|
||||||
## State Transitions
|
|
||||||
|
|
||||||
State transitions are triggered by the following messages:
|
|
||||||
- LinkAssertion
|
|
||||||
- LinkAuthentication
|
|
||||||
- UnlinkAssertion
|
|
||||||
- UnlinkAuthentication
|
|
||||||
- ExecuteTx
|
|
||||||
- UpdateParams
|
|
||||||
|
|
||||||
## Messages
|
|
||||||
|
|
||||||
The DID module defines the following messages:
|
|
||||||
|
|
||||||
1. MsgLinkAuthentication
|
|
||||||
2. MsgLinkAssertion
|
|
||||||
3. MsgExecuteTx
|
|
||||||
4. MsgUnlinkAssertion
|
|
||||||
5. MsgUnlinkAuthentication
|
|
||||||
6. MsgUpdateParams
|
|
||||||
|
|
||||||
Each message triggers specific state machine behaviors related to managing DIDs, authentications, assertions, and module parameters.
|
|
||||||
|
|
||||||
## Query
|
|
||||||
|
|
||||||
The DID module provides the following query endpoints:
|
|
||||||
|
|
||||||
1. Params: Query all parameters of the module
|
|
||||||
2. Resolve: Query the DID document by its ID
|
|
||||||
3. Sign: Sign a message with the DID document
|
|
||||||
4. Verify: Verify a message with the DID document
|
|
||||||
|
|
||||||
## Params
|
|
||||||
|
|
||||||
The module parameters include:
|
|
||||||
- Allowed public keys (map of KeyInfo)
|
|
||||||
- Conveyance preference
|
|
||||||
- Attestation formats
|
|
||||||
|
|
||||||
## Client
|
|
||||||
|
|
||||||
The module provides gRPC and REST endpoints for all defined messages and queries.
|
|
||||||
|
|
||||||
## Future Improvements
|
|
||||||
|
|
||||||
Potential future improvements could include:
|
|
||||||
1. Enhanced privacy features for DID operations
|
|
||||||
2. Integration with more blockchain networks
|
|
||||||
3. Support for additional key types and cryptographic algorithms
|
|
||||||
4. Improved revocation mechanisms for credentials and assertions
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
Acceptance tests should cover all major functionality, including:
|
|
||||||
- Creating and managing DIDs
|
|
||||||
- Linking and unlinking assertions and authentications
|
|
||||||
- Executing transactions with DIDs
|
|
||||||
- Querying and resolving DIDs
|
|
||||||
- Parameter updates
|
|
||||||
|
|
||||||
## Appendix
|
|
||||||
|
|
||||||
### Account
|
|
||||||
|
|
||||||
An Account represents a user's identity within the Sonr ecosystem. It includes information such as the user's public key, associated wallets, and other identification details.
|
|
||||||
|
|
||||||
### Decentralized Identifier (DID)
|
|
||||||
|
|
||||||
A Decentralized Identifier (DID) is a unique identifier that is created, owned, and controlled by the user. It is used to establish a secure and verifiable digital identity.
|
|
||||||
|
|
||||||
### Verifiable Credential (VC)
|
|
||||||
|
|
||||||
A Verifiable Credential (VC) is a digital statement that can be cryptographically verified. It contains claims about a subject (e.g., a user) and is issued by a trusted authority.
|
|
||||||
|
|
||||||
### Key Types
|
|
||||||
|
|
||||||
The module supports various key types, including:
|
|
||||||
- Role
|
|
||||||
- Algorithm (e.g., ES256, EdDSA, ES256K)
|
|
||||||
- Encoding (e.g., hex, base64, multibase)
|
|
||||||
- Curve (e.g., P256, P384, P521, X25519, X448, Ed25519, Ed448, secp256k1)
|
|
||||||
|
|
||||||
### JSON Web Key (JWK)
|
|
||||||
|
|
||||||
The module supports JSON Web Keys (JWK) for representing cryptographic keys, including properties such as key type (kty), curve (crv), and coordinates (x, y) for EC and OKP keys, as well as modulus (n) and exponent (e) for RSA keys.
|
|
@ -1,145 +0,0 @@
|
|||||||
# `x/dwn`
|
|
||||||
|
|
||||||
The DWN module is responsible for the management of IPFS deployed Decentralized Web Nodes (DWNs) and their associated data.
|
|
||||||
|
|
||||||
## Concepts
|
|
||||||
|
|
||||||
The DWN module introduces several key concepts:
|
|
||||||
|
|
||||||
1. Decentralized Web Node (DWN): A distributed network for storing and sharing data.
|
|
||||||
2. Schema: A structure defining the format of various data types in the dwn.
|
|
||||||
3. IPFS Integration: The module can interact with IPFS for decentralized data storage.
|
|
||||||
|
|
||||||
## State
|
|
||||||
|
|
||||||
The DWN module maintains the following state:
|
|
||||||
|
|
||||||
### DWN State
|
|
||||||
|
|
||||||
The DWN state is stored using the following structure:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message DWN {
|
|
||||||
uint64 id = 1;
|
|
||||||
string alias = 2;
|
|
||||||
string cid = 3;
|
|
||||||
string resolver = 4;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This state is indexed by ID, alias, and CID for efficient querying.
|
|
||||||
|
|
||||||
### Params State
|
|
||||||
|
|
||||||
The module parameters are stored in the following structure:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Params {
|
|
||||||
bool ipfs_active = 1;
|
|
||||||
bool local_registration_enabled = 2;
|
|
||||||
Schema schema = 4;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Schema State
|
|
||||||
|
|
||||||
The Schema state defines the structure for various data types:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Schema {
|
|
||||||
int32 version = 1;
|
|
||||||
string account = 2;
|
|
||||||
string asset = 3;
|
|
||||||
string chain = 4;
|
|
||||||
string credential = 5;
|
|
||||||
string did = 6;
|
|
||||||
string jwk = 7;
|
|
||||||
string grant = 8;
|
|
||||||
string keyshare = 9;
|
|
||||||
string profile = 10;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## State Transitions
|
|
||||||
|
|
||||||
State transitions in the DWN module are primarily triggered by:
|
|
||||||
|
|
||||||
1. Updating module parameters
|
|
||||||
2. Allocating new dwns
|
|
||||||
3. Syncing DID documents
|
|
||||||
|
|
||||||
## Messages
|
|
||||||
|
|
||||||
The DWN module defines the following message:
|
|
||||||
|
|
||||||
1. `MsgUpdateParams`: Used to update the module parameters.
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message MsgUpdateParams {
|
|
||||||
string authority = 1;
|
|
||||||
Params params = 2;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Begin Block
|
|
||||||
|
|
||||||
No specific begin-block operations are defined for this module.
|
|
||||||
|
|
||||||
## End Block
|
|
||||||
|
|
||||||
No specific end-block operations are defined for this module.
|
|
||||||
|
|
||||||
## Hooks
|
|
||||||
|
|
||||||
The DWN module does not define any hooks.
|
|
||||||
|
|
||||||
## Events
|
|
||||||
|
|
||||||
The DWN module does not explicitly define any events. However, standard Cosmos SDK events may be emitted during state transitions.
|
|
||||||
|
|
||||||
## Client
|
|
||||||
|
|
||||||
The DWN module provides the following gRPC query endpoints:
|
|
||||||
|
|
||||||
1. `Params`: Queries all parameters of the module.
|
|
||||||
2. `Schema`: Queries the DID document schema.
|
|
||||||
3. `Allocate`: Initializes a Target DWN available for claims.
|
|
||||||
4. `Sync`: Queries the DID document by its ID and returns required information.
|
|
||||||
|
|
||||||
## Params
|
|
||||||
|
|
||||||
The module parameters include:
|
|
||||||
|
|
||||||
- `ipfs_active` (bool): Indicates if IPFS integration is active.
|
|
||||||
- `local_registration_enabled` (bool): Indicates if local registration is enabled.
|
|
||||||
- `schema` (Schema): Defines the structure for various data types in the dwn.
|
|
||||||
|
|
||||||
## Future Improvements
|
|
||||||
|
|
||||||
Potential future improvements could include:
|
|
||||||
|
|
||||||
1. Enhanced IPFS integration features.
|
|
||||||
2. Additional authentication mechanisms beyond WebAuthn.
|
|
||||||
3. Improved DID document management and querying capabilities.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
Acceptance tests should cover:
|
|
||||||
|
|
||||||
1. Parameter updates
|
|
||||||
2. DWN state management
|
|
||||||
3. Schema queries
|
|
||||||
4. DWN allocation process
|
|
||||||
5. DID document syncing
|
|
||||||
|
|
||||||
## Appendix
|
|
||||||
|
|
||||||
| Concept | Description |
|
|
||||||
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| Decentralized Web Node (DWN) | A decentralized, distributed, and secure network of nodes that store and share data. It is a decentralized alternative to traditional web hosting services. |
|
|
||||||
| Decentralized Identifier (DID) | A unique identifier that is created, owned, and controlled by the user. It is used to establish a secure and verifiable digital identity. |
|
|
||||||
| HTMX (Hypertext Markup Language eXtensions) | A set of extensions to HTML that allow for the creation of interactive web pages. It is used to enhance the user experience and provide additional functionality to web applications. |
|
|
||||||
| IPFS (InterPlanetary File System) | A decentralized, peer-to-peer network for storing and sharing data. It is a distributed file system that allows for the creation and sharing of content across a network of nodes. |
|
|
||||||
| WebAuthn (Web Authentication) | A set of APIs that allow websites to request user authentication using biometric or non-biometric factors. |
|
|
||||||
| WebAssembly (Web Assembly) | A binary instruction format for a stack-based virtual machine. |
|
|
||||||
| Verifiable Credential (VC) | A digital statement that can be cryptographically verified. |
|
|
@ -1,91 +0,0 @@
|
|||||||
# `x/svc`
|
|
||||||
|
|
||||||
The svc module is responsible for managing the registration and authorization of services within the Sonr ecosystem. It provides a secure and verifiable mechanism for registering and authorizing services using Decentralized Identifiers (DIDs).
|
|
||||||
|
|
||||||
## Concepts
|
|
||||||
|
|
||||||
- **Service**: A decentralized svc on the Sonr Blockchain with properties such as ID, authority, origin, name, description, category, tags, and expiry height.
|
|
||||||
- **Profile**: Represents a DID alias with properties like ID, subject, origin, and controller.
|
|
||||||
- **Metadata**: Contains information about a svc, including name, description, category, icon, and tags.
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
|
|
||||||
- [x/did](https://github.com/onsonr/sonr/tree/master/x/did)
|
|
||||||
- [x/group](https://github.com/onsonr/sonr/tree/master/x/group)
|
|
||||||
- [x/nft](https://github.com/onsonr/sonr/tree/master/x/nft)
|
|
||||||
|
|
||||||
## State
|
|
||||||
|
|
||||||
The module uses the following state structures:
|
|
||||||
|
|
||||||
### Metadata
|
|
||||||
|
|
||||||
Stores information about services:
|
|
||||||
|
|
||||||
- Primary key: `id` (auto-increment)
|
|
||||||
- Unique index: `origin`
|
|
||||||
- Fields: id, origin, name, description, category, icon (URI), tags
|
|
||||||
|
|
||||||
### Profile
|
|
||||||
|
|
||||||
Stores DID alias information:
|
|
||||||
|
|
||||||
- Primary key: `id`
|
|
||||||
- Unique index: `subject,origin`
|
|
||||||
- Fields: id, subject, origin, controller
|
|
||||||
|
|
||||||
## Messages
|
|
||||||
|
|
||||||
### MsgUpdateParams
|
|
||||||
|
|
||||||
Updates the module parameters. Can only be executed by the governance account.
|
|
||||||
|
|
||||||
### MsgRegisterService
|
|
||||||
|
|
||||||
Registers a new svc on the blockchain. Requires a valid TXT record in DNS for the origin.
|
|
||||||
|
|
||||||
## Params
|
|
||||||
|
|
||||||
The module has the following parameters:
|
|
||||||
|
|
||||||
- `categories`: List of allowed svc categories
|
|
||||||
- `types`: List of allowed svc types
|
|
||||||
|
|
||||||
## Query
|
|
||||||
|
|
||||||
The module provides the following query:
|
|
||||||
|
|
||||||
### Params
|
|
||||||
|
|
||||||
Retrieves all parameters of the module.
|
|
||||||
|
|
||||||
## Client
|
|
||||||
|
|
||||||
### gRPC
|
|
||||||
|
|
||||||
The module provides a gRPC Query svc with the following RPC:
|
|
||||||
|
|
||||||
- `Params`: Get all parameters of the module
|
|
||||||
|
|
||||||
### CLI
|
|
||||||
|
|
||||||
(TODO: Add CLI commands for interacting with the module)
|
|
||||||
|
|
||||||
## Events
|
|
||||||
|
|
||||||
(TODO: List and describe event tags used by the module)
|
|
||||||
|
|
||||||
## Future Improvements
|
|
||||||
|
|
||||||
- Implement svc discovery mechanisms
|
|
||||||
- Add support for svc reputation and rating systems
|
|
||||||
- Enhance svc metadata with more detailed information
|
|
||||||
- Implement svc update and deactivation functionality
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
(TODO: Add acceptance tests for the module)
|
|
||||||
|
|
||||||
## Appendix
|
|
||||||
|
|
||||||
This module is part of the Sonr blockchain project and interacts with other modules such as DID and NFT modules to provide a comprehensive decentralized svc ecosystem.
|
|
@ -1,329 +0,0 @@
|
|||||||
# ORM
|
|
||||||
|
|
||||||
The Cosmos SDK ORM is a state management library that provides a rich, but opinionated set of tools for managing a
|
|
||||||
module's state. It provides support for:
|
|
||||||
|
|
||||||
- type safe management of state
|
|
||||||
- multipart keys
|
|
||||||
- secondary indexes
|
|
||||||
- unique indexes
|
|
||||||
- easy prefix and range queries
|
|
||||||
- automatic genesis import/export
|
|
||||||
- automatic query services for clients, including support for light client proofs (still in development)
|
|
||||||
- indexing state data in external databases (still in development)
|
|
||||||
|
|
||||||
## Design and Philosophy
|
|
||||||
|
|
||||||
The ORM's data model is inspired by the relational data model found in SQL databases. The core abstraction is a table
|
|
||||||
with a primary key and optional secondary indexes.
|
|
||||||
|
|
||||||
Because the Cosmos SDK uses protobuf as its encoding layer, ORM tables are defined directly in .proto files using
|
|
||||||
protobuf options. Each table is defined by a single protobuf `message` type and a schema of multiple tables is
|
|
||||||
represented by a single .proto file.
|
|
||||||
|
|
||||||
Table structure is specified in the same file where messages are defined in order to make it easy to focus on better
|
|
||||||
design of the state layer. Because blockchain state layout is part of the public API for clients (TODO: link to docs on
|
|
||||||
light client proofs), it is important to think about the state layout as being part of the public API of a module.
|
|
||||||
Changing the state layout actually breaks clients, so it is ideal to think through it carefully up front and to aim for
|
|
||||||
a design that will eliminate or minimize breaking changes down the road. Also, good design of state enables building
|
|
||||||
more performant and sophisticated applications. Providing users with a set of tools inspired by relational databases
|
|
||||||
which have a long history of database design best practices and allowing schema to be specified declaratively in a
|
|
||||||
single place are design choices the ORM makes to enable better design and more durable APIs.
|
|
||||||
|
|
||||||
Also, by only supporting the table abstraction as opposed to key-value pair maps, it is easy to add to new
|
|
||||||
columns/fields to any data structure without causing a breaking change and the data structures can easily be indexed in
|
|
||||||
any off-the-shelf SQL database for more sophisticated queries.
|
|
||||||
|
|
||||||
The encoding of fields in keys is designed to support ordered iteration for all protobuf primitive field types
|
|
||||||
except for `bytes` as well as the well-known types `google.protobuf.Timestamp` and `google.protobuf.Duration`. Encodings
|
|
||||||
are optimized for storage space when it makes sense (see the documentation in `cosmos/orm/v1/orm.proto` for more details)
|
|
||||||
and table rows do not use extra storage space to store key fields in the value.
|
|
||||||
|
|
||||||
We recommend that users of the ORM attempt to follow database design best practices such as
|
|
||||||
[normalization](https://en.wikipedia.org/wiki/Database_normalization) (at least 1NF).
|
|
||||||
For instance, defining `repeated` fields in a table is considered an anti-pattern because breaks first normal form (1NF).
|
|
||||||
Although we support `repeated` fields in tables, they cannot be used as key fields for this reason. This may seem
|
|
||||||
restrictive but years of best practice (and also experience in the SDK) have shown that following this pattern
|
|
||||||
leads to easier to maintain schemas.
|
|
||||||
|
|
||||||
To illustrate the motivation for these principles with an example from the SDK, historically balances were stored
|
|
||||||
as a mapping from account -> map of denom to amount. This did not scale well because an account with 100 token balances
|
|
||||||
needed to be encoded/decoded every time a single coin balance changed. Now balances are stored as account,denom -> amount
|
|
||||||
as in the example above. With the ORM's data model, if we wanted to add a new field to `Balance` such as
|
|
||||||
`unlocked_balance` (if vesting accounts were redesigned in this way), it would be easy to add it to this table without
|
|
||||||
requiring a data migration. Because of the ORM's optimizations, the account and denom are only stored in the key part
|
|
||||||
of storage and not in the value leading to both a flexible data model and efficient usage of storage.
|
|
||||||
|
|
||||||
## Defining Tables
|
|
||||||
|
|
||||||
To define a table:
|
|
||||||
|
|
||||||
1. create a .proto file to describe the module's state (naming it `state.proto` is recommended for consistency),
|
|
||||||
and import "cosmos/orm/v1/orm.proto", ex:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
syntax = "proto3";
|
|
||||||
package bank_example;
|
|
||||||
|
|
||||||
import "cosmos/orm/v1/orm.proto";
|
|
||||||
```
|
|
||||||
|
|
||||||
2. define a `message` for the table, ex:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Balance {
|
|
||||||
bytes account = 1;
|
|
||||||
string denom = 2;
|
|
||||||
uint64 balance = 3;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. add the `cosmos.orm.v1.table` option to the table and give the table an `id` unique within this .proto file:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Balance {
|
|
||||||
option (cosmos.orm.v1.table) = {
|
|
||||||
id: 1
|
|
||||||
};
|
|
||||||
|
|
||||||
bytes account = 1;
|
|
||||||
string denom = 2;
|
|
||||||
uint64 balance = 3;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
4. define the primary key field or fields, as a comma-separated list of the fields from the message which should make
|
|
||||||
up the primary key:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Balance {
|
|
||||||
option (cosmos.orm.v1.table) = {
|
|
||||||
id: 1
|
|
||||||
primary_key: { fields: "account,denom" }
|
|
||||||
};
|
|
||||||
|
|
||||||
bytes account = 1;
|
|
||||||
string denom = 2;
|
|
||||||
uint64 balance = 3;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
5. add any desired secondary indexes by specifying an `id` unique within the table and a comma-separate list of the
|
|
||||||
index fields:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Balance {
|
|
||||||
option (cosmos.orm.v1.table) = {
|
|
||||||
id: 1;
|
|
||||||
primary_key: { fields: "account,denom" }
|
|
||||||
index: { id: 1 fields: "denom" } // this allows querying for the accounts which own a denom
|
|
||||||
};
|
|
||||||
|
|
||||||
bytes account = 1;
|
|
||||||
string denom = 2;
|
|
||||||
uint64 amount = 3;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Auto-incrementing Primary Keys
|
|
||||||
|
|
||||||
A common pattern in SDK modules and in database design is to define tables with a single integer `id` field with an
|
|
||||||
automatically generated primary key. In the ORM we can do this by setting the `auto_increment` option to `true` on the
|
|
||||||
primary key, ex:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Account {
|
|
||||||
option (cosmos.orm.v1.table) = {
|
|
||||||
id: 2;
|
|
||||||
primary_key: { fields: "id", auto_increment: true }
|
|
||||||
};
|
|
||||||
|
|
||||||
uint64 id = 1;
|
|
||||||
bytes address = 2;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Unique Indexes
|
|
||||||
|
|
||||||
A unique index can be added by setting the `unique` option to `true` on an index, ex:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Account {
|
|
||||||
option (cosmos.orm.v1.table) = {
|
|
||||||
id: 2;
|
|
||||||
primary_key: { fields: "id", auto_increment: true }
|
|
||||||
index: {id: 1, fields: "address", unique: true}
|
|
||||||
};
|
|
||||||
|
|
||||||
uint64 id = 1;
|
|
||||||
bytes address = 2;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Singletons
|
|
||||||
|
|
||||||
The ORM also supports a special type of table with only one row called a `singleton`. This can be used for storing
|
|
||||||
module parameters. Singletons only need to define a unique `id` and that cannot conflict with the id of other
|
|
||||||
tables or singletons in the same .proto file. Ex:
|
|
||||||
|
|
||||||
```protobuf
|
|
||||||
message Params {
|
|
||||||
option (cosmos.orm.v1.singleton) = {
|
|
||||||
id: 3;
|
|
||||||
};
|
|
||||||
|
|
||||||
google.protobuf.Duration voting_period = 1;
|
|
||||||
uint64 min_threshold = 2;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running Codegen
|
|
||||||
|
|
||||||
NOTE: the ORM will only work with protobuf code that implements the [google.golang.org/protobuf](https://pkg.go.dev/google.golang.org/protobuf)
|
|
||||||
API. That means it will not work with code generated using gogo-proto.
|
|
||||||
|
|
||||||
To install the ORM's code generator, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
go install cosmossdk.io/orm/cmd/protoc-gen-go-cosmos-orm@latest
|
|
||||||
```
|
|
||||||
|
|
||||||
The recommended way to run the code generator is to use [buf build](https://docs.buf.build/build/usage).
|
|
||||||
This is an example `buf.gen.yaml` that runs `protoc-gen-go`, `protoc-gen-go-grpc` and `protoc-gen-go-cosmos-orm`
|
|
||||||
using buf managed mode:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: v1
|
|
||||||
managed:
|
|
||||||
enabled: true
|
|
||||||
go_package_prefix:
|
|
||||||
default: foo.bar/api # the go package prefix of your package
|
|
||||||
override:
|
|
||||||
buf.build/cosmos/cosmos-sdk: cosmossdk.io/api # required to import the Cosmos SDK api module
|
|
||||||
plugins:
|
|
||||||
- name: go
|
|
||||||
out: .
|
|
||||||
opt: paths=source_relative
|
|
||||||
- name: go-grpc
|
|
||||||
out: .
|
|
||||||
opt: paths=source_relative
|
|
||||||
- name: go-cosmos-orm
|
|
||||||
out: .
|
|
||||||
opt: paths=source_relative
|
|
||||||
```
|
|
||||||
|
|
||||||
## Using the ORM in a module
|
|
||||||
|
|
||||||
### Initialization
|
|
||||||
|
|
||||||
To use the ORM in a module, first create a `ModuleSchemaDescriptor`. This tells the ORM which .proto files have defined
|
|
||||||
an ORM schema and assigns them all a unique non-zero id. Ex:
|
|
||||||
|
|
||||||
```go
|
|
||||||
var MyModuleSchema = &ormv1alpha1.ModuleSchemaDescriptor{
|
|
||||||
SchemaFile: []*ormv1alpha1.ModuleSchemaDescriptor_FileEntry{
|
|
||||||
{
|
|
||||||
Id: 1,
|
|
||||||
ProtoFileName: mymodule.File_my_module_state_proto.Path(),
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
In the ORM generated code for a file named `state.proto`, there should be an interface `StateStore` that got generated
|
|
||||||
with a constructor `NewStateStore` that takes a parameter of type `ormdb.ModuleDB`. Add a reference to `StateStore`
|
|
||||||
to your module's keeper struct. Ex:
|
|
||||||
|
|
||||||
```go
|
|
||||||
type Keeper struct {
|
|
||||||
db StateStore
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Then instantiate the `StateStore` instance via an `ormdb.ModuleDB` that is instantiated from the `SchemaDescriptor`
|
|
||||||
above and one or more store services from `cosmossdk.io/core/store`. Ex:
|
|
||||||
|
|
||||||
```go
|
|
||||||
func NewKeeper(storeService store.KVStoreService) (*Keeper, error) {
|
|
||||||
modDb, err := ormdb.NewModuleDB(MyModuleSchema, ormdb.ModuleDBOptions{KVStoreService: storeService})
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
db, err := NewStateStore(modDb)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
return Keeper{db: db}, nil
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Using the generated code
|
|
||||||
|
|
||||||
The generated code for the ORM contains methods for inserting, updating, deleting and querying table entries.
|
|
||||||
For each table in a .proto file, there is a type-safe table interface implemented in generated code. For instance,
|
|
||||||
for a table named `Balance` there should be a `BalanceTable` interface that looks like this:
|
|
||||||
|
|
||||||
```go
|
|
||||||
type BalanceTable interface {
|
|
||||||
Insert(ctx context.Context, balance *Balance) error
|
|
||||||
Update(ctx context.Context, balance *Balance) error
|
|
||||||
Save(ctx context.Context, balance *Balance) error
|
|
||||||
Delete(ctx context.Context, balance *Balance) error
|
|
||||||
Has(ctx context.Context, account []byte, denom string) (found bool, err error)
|
|
||||||
// Get returns nil and an error which responds true to ormerrors.IsNotFound() if the record was not found.
|
|
||||||
Get(ctx context.Context, account []byte, denom string) (*Balance, error)
|
|
||||||
List(ctx context.Context, prefixKey BalanceIndexKey, opts ...ormlist.Option) (BalanceIterator, error)
|
|
||||||
ListRange(ctx context.Context, from, to BalanceIndexKey, opts ...ormlist.Option) (BalanceIterator, error)
|
|
||||||
DeleteBy(ctx context.Context, prefixKey BalanceIndexKey) error
|
|
||||||
DeleteRange(ctx context.Context, from, to BalanceIndexKey) error
|
|
||||||
|
|
||||||
doNotImplement()
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
This `BalanceTable` should be accessible from the `StateStore` interface (assuming our file is named `state.proto`)
|
|
||||||
via a `BalanceTable()` accessor method. If all the above example tables/singletons were in the same `state.proto`,
|
|
||||||
then `StateStore` would get generated like this:
|
|
||||||
|
|
||||||
```go
|
|
||||||
type BankStore interface {
|
|
||||||
BalanceTable() BalanceTable
|
|
||||||
AccountTable() AccountTable
|
|
||||||
ParamsTable() ParamsTable
|
|
||||||
|
|
||||||
doNotImplement()
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
So to work with the `BalanceTable` in a keeper method we could use code like this:
|
|
||||||
|
|
||||||
```go
|
|
||||||
func (k keeper) AddBalance(ctx context.Context, acct []byte, denom string, amount uint64) error {
|
|
||||||
balance, err := k.db.BalanceTable().Get(ctx, acct, denom)
|
|
||||||
if err != nil && !ormerrors.IsNotFound(err) {
|
|
||||||
return err
|
|
||||||
}
|
|
||||||
|
|
||||||
if balance == nil {
|
|
||||||
balance = &Balance{
|
|
||||||
Account: acct,
|
|
||||||
Denom: denom,
|
|
||||||
Amount: amount,
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
balance.Amount = balance.Amount + amount
|
|
||||||
}
|
|
||||||
|
|
||||||
return k.db.BalanceTable().Save(ctx, balance)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`List` methods take `IndexKey` parameters. For instance, `BalanceTable.List` takes `BalanceIndexKey`. `BalanceIndexKey`
|
|
||||||
let's represent index keys for the different indexes (primary and secondary) on the `Balance` table. The primary key
|
|
||||||
in the `Balance` table gets a struct `BalanceAccountDenomIndexKey` and the first index gets an index key `BalanceDenomIndexKey`.
|
|
||||||
If we wanted to list all the denoms and amounts that an account holds, we would use `BalanceAccountDenomIndexKey`
|
|
||||||
with a `List` query just on the account prefix. Ex:
|
|
||||||
|
|
||||||
```go
|
|
||||||
it, err := keeper.db.BalanceTable().List(ctx, BalanceAccountDenomIndexKey{}.WithAccount(acct))
|
|
||||||
```
|
|
@ -1,3 +0,0 @@
|
|||||||
# Cosmos SDK
|
|
||||||
|
|
||||||
The Cosmos SDK is a modular framework for building blockchain applications. Sonr is built on top of the Cosmos SDK, which provides a robust and secure foundation for building decentralized applications.
|
|
@ -1,3 +0,0 @@
|
|||||||
# Echo Framework
|
|
||||||
|
|
||||||
The Echo Framework is a web framework for building RESTful APIs in Go. It provides a simple and intuitive way to define routes, handle requests, and return responses. It uses `net/http` underneath to provide minimal external dependencies.
|
|
@ -1,3 +0,0 @@
|
|||||||
# Templ Syntax
|
|
||||||
|
|
||||||
Templ is a template engine for Go that provides a simple and intuitive way to generate dynamic content.
|
|
@ -1,3 +0,0 @@
|
|||||||
# WebAwesome Components
|
|
||||||
|
|
||||||
WebAwesome Components is a collection of reusable web components for building web applications. It provides a set of pre-built components that can be easily integrated into your web application.
|
|
3
go.mod
3
go.mod
@ -66,7 +66,6 @@ require (
|
|||||||
github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0
|
github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0
|
||||||
github.com/dustinxie/ecc v0.0.0-20210511000915-959544187564
|
github.com/dustinxie/ecc v0.0.0-20210511000915-959544187564
|
||||||
github.com/ecies/go/v2 v2.0.9
|
github.com/ecies/go/v2 v2.0.9
|
||||||
github.com/ethereum/go-ethereum v1.14.6
|
|
||||||
github.com/go-webauthn/webauthn v0.11.2
|
github.com/go-webauthn/webauthn v0.11.2
|
||||||
github.com/golang-jwt/jwt v3.2.2+incompatible
|
github.com/golang-jwt/jwt v3.2.2+incompatible
|
||||||
github.com/golang/protobuf v1.5.4
|
github.com/golang/protobuf v1.5.4
|
||||||
@ -144,6 +143,7 @@ require (
|
|||||||
github.com/dustin/go-humanize v1.0.1 // indirect
|
github.com/dustin/go-humanize v1.0.1 // indirect
|
||||||
github.com/dvsekhvalnov/jose2go v1.6.0 // indirect
|
github.com/dvsekhvalnov/jose2go v1.6.0 // indirect
|
||||||
github.com/emicklei/dot v1.6.1 // indirect
|
github.com/emicklei/dot v1.6.1 // indirect
|
||||||
|
github.com/ethereum/go-ethereum v1.14.6 // indirect
|
||||||
github.com/fatih/color v1.16.0 // indirect
|
github.com/fatih/color v1.16.0 // indirect
|
||||||
github.com/felixge/httpsnoop v1.0.4 // indirect
|
github.com/felixge/httpsnoop v1.0.4 // indirect
|
||||||
github.com/fsnotify/fsnotify v1.7.0 // indirect
|
github.com/fsnotify/fsnotify v1.7.0 // indirect
|
||||||
@ -188,7 +188,6 @@ require (
|
|||||||
github.com/hashicorp/hcl v1.0.0 // indirect
|
github.com/hashicorp/hcl v1.0.0 // indirect
|
||||||
github.com/hashicorp/yamux v0.1.1 // indirect
|
github.com/hashicorp/yamux v0.1.1 // indirect
|
||||||
github.com/hdevalence/ed25519consensus v0.1.0 // indirect
|
github.com/hdevalence/ed25519consensus v0.1.0 // indirect
|
||||||
github.com/holiman/uint256 v1.2.4 // indirect
|
|
||||||
github.com/huandu/skiplist v1.2.0 // indirect
|
github.com/huandu/skiplist v1.2.0 // indirect
|
||||||
github.com/iancoleman/orderedmap v0.3.0 // indirect
|
github.com/iancoleman/orderedmap v0.3.0 // indirect
|
||||||
github.com/iancoleman/strcase v0.3.0 // indirect
|
github.com/iancoleman/strcase v0.3.0 // indirect
|
||||||
|
2
go.sum
2
go.sum
@ -1561,8 +1561,6 @@ github.com/holiman/billy v0.0.0-20230718173358-1c7e68d277a7/go.mod h1:5GuXa7vkL8
|
|||||||
github.com/holiman/bloomfilter/v2 v2.0.3/go.mod h1:zpoh+gs7qcpqrHr3dB55AMiJwo0iURXE7ZOP9L9hSkA=
|
github.com/holiman/bloomfilter/v2 v2.0.3/go.mod h1:zpoh+gs7qcpqrHr3dB55AMiJwo0iURXE7ZOP9L9hSkA=
|
||||||
github.com/holiman/uint256 v1.2.0/go.mod h1:y4ga/t+u+Xwd7CpDgZESaRcWy0I7XMlTMA25ApIH5Jw=
|
github.com/holiman/uint256 v1.2.0/go.mod h1:y4ga/t+u+Xwd7CpDgZESaRcWy0I7XMlTMA25ApIH5Jw=
|
||||||
github.com/holiman/uint256 v1.2.3/go.mod h1:SC8Ryt4n+UBbPbIBKaG9zbbDlp4jOru9xFZmPzLUTxw=
|
github.com/holiman/uint256 v1.2.3/go.mod h1:SC8Ryt4n+UBbPbIBKaG9zbbDlp4jOru9xFZmPzLUTxw=
|
||||||
github.com/holiman/uint256 v1.2.4 h1:jUc4Nk8fm9jZabQuqr2JzednajVmBpC+oiTiXZJEApU=
|
|
||||||
github.com/holiman/uint256 v1.2.4/go.mod h1:EOMSn4q6Nyt9P6efbI3bueV4e1b3dGlUCXeiRV4ng7E=
|
|
||||||
github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
|
github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
|
||||||
github.com/huandu/go-assert v1.1.5 h1:fjemmA7sSfYHJD7CUqs9qTwwfdNAx7/j2/ZlHXzNB3c=
|
github.com/huandu/go-assert v1.1.5 h1:fjemmA7sSfYHJD7CUqs9qTwwfdNAx7/j2/ZlHXzNB3c=
|
||||||
github.com/huandu/go-assert v1.1.5/go.mod h1:yOLvuqZwmcHIC5rIzrBhT7D3Q9c3GFnd0JrPVhn/06U=
|
github.com/huandu/go-assert v1.1.5/go.mod h1:yOLvuqZwmcHIC5rIzrBhT7D3Q9c3GFnd0JrPVhn/06U=
|
||||||
|
Loading…
x
Reference in New Issue
Block a user