Skip to main content

Client

The x/notary module exposes two primary services for interacting with the blockchain:

  • Query Service: Read-only operations to query module state
  • Msg Service: State-changing operations (transactions)

Both services are accessible via gRPC, REST API, and CLI.

Query Service​

The Query service provides read-only access to notary module state.

Package: d.notary.v1.Query

gRPC Service Name: /d.notary.v1.Query

GetNotaryInfoById​

Retrieves a specific NotaryInfo configuration by its ID, including its VCV route configurations.

gRPC Method: /d.notary.v1.Query/GetNotaryInfoById

REST Endpoint: GET /d/notary/v1/notary_info?id={id}

Request:

message GetNotaryInfoByIdRequest {
  uint64 id = 1;
}

Response:

message GetNotaryInfoByIdResponse {
  NotaryInfo notary_info = 1;
  d.vcv.v1.RouteAndAdditionalReq vcv_route_and_additional_req = 2;
}

VCV Integration: The response includes the VCV route configuration, showing which verifier contracts and routes are used for caller and asset verification.

GetNotaryInfoNextId​

Retrieves the next available NotaryInfo ID (useful for predicting the ID before registration).

gRPC Method: /d.notary.v1.Query/GetNotaryInfoNextId

REST Endpoint: GET /d/notary/v1/notary_info_next_id

Request:

message GetNotaryInfoNextIdRequest {}

Response:

message GetNotaryInfoNextIdResponse {
  uint64 next_id = 1;
}

GetCurrencyConversionRate​

Retrieves the conversion rate for a specific currency to EUR.

gRPC Method: /d.notary.v1.Query/GetCurrencyConversionRate

REST Endpoint: GET /d/notary/v1/currency_conversion_rate/{currency}

Request:

message GetCurrencyConversionRateRequest {
  string currency = 1;  // e.g., "USD", "EUR", "GBP"
}

Response:

message GetCurrencyConversionRateResponse {
  string rate = 1;  // Decimal string (e.g., "0.85")
}

GetEurPriceInUdt​

Retrieves how many udt (micro-tokens) equal 1 EUR.

gRPC Method: /d.notary.v1.Query/GetEurPriceInUdt

REST Endpoint: GET /d/notary/v1/eur_price_in_udt

Request:

message GetEurPriceInUdtRequest {}

Response:

message GetEurPriceInUdtResponse {
  string price = 1;  // Decimal string (e.g., "250000000" for 250M udt = 1 EUR)
}

GetNotarisationFeeRate​

Retrieves the current notarisation fee rate (as a percentage).

gRPC Method: /d.notary.v1.Query/GetNotarisationFeeRate

REST Endpoint: GET /d/notary/v1/notarisation_fee_rate

Request:

message GetNotarisationFeeRateRequest {}

Response:

message GetNotarisationFeeRateResponse {
  string rate = 1;  // Decimal string (e.g., "0.005" for 0.5%)
}

GetNotarisedAsset​

Retrieves a specific notarised asset by its ID.

gRPC Method: /d.notary.v1.Query/GetNotarisedAsset

REST Endpoint: GET /d/notary/v1/notarised_asset/{asset_id}

Request:

message GetNotarisedAssetRequest {
  string asset_id = 1;
}

Response:

message GetNotarisedAssetResponse {
  NotarisedAsset notarised_asset = 1;
}

GetNotarisedAssets​

Retrieves all notarised assets with pagination support.

gRPC Method: /d.notary.v1.Query/GetNotarisedAssets

REST Endpoint: GET /d/notary/v1/notarised_assets

Request:

message GetNotarisedAssetsRequest {
  cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

Response:

message GetNotarisedAssetsResponse {
  repeated NotarisedAssetEntry notarised_assets = 1;
  cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

Msg Service (Transactions)​

The Msg service handles state-changing operations. All transactions require proper signatures and may require VCV verification.

Package: d.notary.v1.Msg

gRPC Service Name: /d.notary.v1.Msg

Notarise​

Notarises an asset by providing verifiable presentations for verification via x/vcv.

gRPC Method: /d.notary.v1.Msg/Notarise

Request:

message MsgNotarise {
  string sender = 1;
  uint64 notary_info_id = 2;
  bytes verifier_input = 3;        // Verifiable presentation for asset verification
  bytes asset_data = 4;            // JSON-encoded asset data
  string owner = 5;                // Optional, defaults to sender
  cosmos.base.v1beta1.Coin max_notarise_fee = 6;  // Optional fee limit
}

Response:

message MsgNotariseResponse {
  uint64 notary_info_id = 1;
  uint64 asset_type_id = 2;
  string notarised_asset_id = 3;  // SHA256 hash of asset data
}

VCV Integration:

  1. Caller verification via VCV AnteHandler (if caller route configured)
  2. Asset verification via VcvKeeper.VerifiablePresentationChecker during execution

Transaction Extensions:

  • Must include verifiable presentation in transaction ExtensionOptions for caller verification
  • The verifier_input parameter contains the VP for asset verification

RegisterNotaryInfo​

Registers a new notary configuration for a DApp.

gRPC Method: /d.notary.v1.Msg/RegisterNotaryInfo

Request:

message MsgRegisterNotaryInfo {
  string sender = 1;
  NotaryInfo notary_info = 2;
  d.vcv.v1.RouteAndAdditionalReq caller_route_and_additional_req = 3;  // Optional
  d.vcv.v1.RouteAndAdditionalReq asset_route_and_additional_req = 4;   // Optional
  uint64 asset_type_id = 5;
}

Response:

message MsgRegisterNotaryInfoResponse {
  uint64 notary_info_id = 1;
}

VCV Integration: Routes are validated via VcvKeeper.CheckAppOrRouteOnVerifier to ensure they exist on verifier contracts before registration.

UpdateVerifierRoutes​

Updates the verification routes for an existing NotaryInfo (admin only).

gRPC Method: /d.notary.v1.Msg/UpdateVerifierRoutes

Request:

message MsgUpdateVerifierRoutes {
  string sender = 1;
  uint64 notary_info_id = 2;
  d.vcv.v1.RouteAndAdditionalReq caller_route_and_additional_req = 3;  // Optional
  d.vcv.v1.RouteAndAdditionalReq asset_route_and_additional_req = 4;   // Optional
}

Response:

message MsgUpdateVerifierRoutesResponse {}

VCV Integration: New routes are validated via VcvKeeper.CheckAppOrRouteOnVerifier. Routes are only updated if explicitly provided (nil-safe).

UpdateAdmin​

Transfers admin rights to a new address (current admin only).

gRPC Method: /d.notary.v1.Msg/UpdateAdmin

Request:

message MsgUpdateAdmin {
  string sender = 1;
  uint64 notary_info_id = 2;
  string new_admin = 3;
}

Response:

message MsgUpdateAdminResponse {}

RemoveNotaryInfo​

Deletes a NotaryInfo configuration (admin only).

gRPC Method: /d.notary.v1.Msg/RemoveNotaryInfo

Request:

message MsgRemoveNotaryInfo {
  string sender = 1;
  uint64 notary_info_id = 2;
}

Response:

message MsgRemoveNotaryInfoResponse {
  uint64 notary_info_id = 1;
}

SetCurrencyConversionRate​

Sets the conversion rate for a currency to EUR (authority only).

gRPC Method: /d.notary.v1.Msg/SetCurrencyConversionRate

Request:

message MsgSetCurrencyConversionRate {
  string sender = 1;              // Must be module authority
  string currency = 2;             // e.g., "USD", "GBP"
  string rate = 3;                 // Decimal string
}

Response:

message MsgSetCurrencyConversionRateResponse {}

SetEurPriceInUdt​

Sets the EUR price in udt (authority only).

gRPC Method: /d.notary.v1.Msg/SetEurPriceInUdt

Request:

message MsgSetEurPriceInUdt {
  string sender = 1;              // Must be module authority
  string price = 2;                // Decimal string
}

Response:

message MsgSetEurPriceInUdtResponse {}

SetNotarisationFeeRate​

Sets the notarisation fee rate (authority only).

gRPC Method: /d.notary.v1.Msg/SetNotarisationFeeRate

Request:

message MsgSetNotarisationFeeRate {
  string sender = 1;              // Must be module authority
  string rate = 2;                 // Decimal string (e.g., "0.005" for 0.5%)
}

Response:

message MsgSetNotarisationFeeRateResponse {}

gRPC Client Examples​

Go gRPC Client​

import (
    "context"
    "google.golang.org/grpc"
    notaryv1 "github.com/d-foundation/protocol/api/d/notary/v1"
)

// Query example
conn, err := grpc.Dial("localhost:9090", grpc.WithInsecure())
queryClient := notaryv1.NewQueryClient(conn)

resp, err := queryClient.GetNotaryInfoById(context.Background(), &notaryv1.GetNotaryInfoByIdRequest{
    Id: 1,
})

// Transaction example
msgClient := notaryv1.NewMsgClient(conn)

resp, err := msgClient.Notarise(context.Background(), &notaryv1.MsgNotarise{
    Sender:         "dchain1...",
    NotaryInfoId:   1,
    VerifierInput:  vpBytes,
    AssetData:      assetDataBytes,
})

REST API Examples​

# Query NotaryInfo
curl http://localhost:1317/d/notary/v1/notary_info?id=1

# Query notarised asset
curl http://localhost:1317/d/notary/v1/notarised_asset/ABC123...

# Query all notarised assets (paginated)
curl http://localhost:1317/d/notary/v1/notarised_assets?pagination.limit=10

# Query fee rate
curl http://localhost:1317/d/notary/v1/notarisation_fee_rate

CLI Commands​

The x/notary module provides CLI commands for both querying state and submitting transactions. CLI configuration is defined in x/notary/module/autocli.go.

Query Commands​

All query commands are prefixed with query notary:

Get NotaryInfo by ID​

dchain query notary notary-info [id]

Get the registered NotaryInfo configuration by its ID.

Example:

dchain query notary notary-info 1

Get Next NotaryInfo ID​

dchain query notary next-id

Get the next available NotaryInfo ID.

Example:

dchain query notary next-id

Get Currency Conversion Rate​

dchain query notary currency-conversion-rate [currency]

Get the conversion rate to EUR for a given currency.

Example:

dchain query notary currency-conversion-rate USD

Get EUR Price in Udt​

dchain query notary eur-price-in-udt

Get the EUR price in udt (micro-tokens).

Example:

dchain query notary eur-price-in-udt

Get Notarisation Fee Rate​

dchain query notary notarisation-fee-rate

Get the current notarisation fee rate.

Example:

dchain query notary notarisation-fee-rate

Get Notarised Asset​

dchain query notary notarised-asset [asset-id]

Get a notarised asset by its ID.

Example:

dchain query notary notarised-asset ABC123XYZ...

Get All Notarised Assets​

dchain query notary notarised-assets

Get all notarised assets (paginated).

Example:

dchain query notary notarised-assets --page=1 --limit=10

Transaction Commands​

All transaction commands are prefixed with tx notary:

Notarise Tx​

dchain tx notary notarise [notary-info-id] [verifier-input] [asset-data] --from [key]

Notarise data under a given NotaryInfo ID. Users are able to bring verifiable data onchain through this call.

VCV Integration: This command requires verifiable presentations for both caller and asset verification via x/vcv.

Example:

dchain tx notary notarise 1 <verifier-input-hex> <asset-data-hex> --from mykey --verifiable-presentation <caller-vp-hex>

Optional Flags:

  • --owner: Specify asset owner (defaults to sender)
  • --max-notarise-fee: Set maximum acceptable notarisation fee
  • --verifiable-presentation: Verifiable presentation for caller verification (hex-encoded)

Register NotaryInfo​

dchain tx notary register [asset-type-id] --from [key]

Register a new NotaryInfo and get a NotaryInfoId back. For decentralised applications to register the NotaryInfo configuration.

VCV Integration: Routes must be specified via flags and will be validated against verifier contracts.

Example:

dchain tx notary register 1 --from mykey

Required Flags:

  • --caller-route-and-additional-req: Caller verification route (JSON)
  • --asset-route-and-additional-req: Asset verification route (JSON)
  • --notary-info-admin: Admin address (optional, defaults to sender)

Update Verifier Routes​

dchain tx notary update-verifier-routes [notary-info-id] --from [key]

Update the verification mechanism of NotaryInfo for a given NotaryInfoId (admin only).

VCV Integration: New routes are validated via VcvKeeper.CheckAppOrRouteOnVerifier.

Example:

dchain tx notary update-verifier-routes 1 --from mykey

Optional Flags:

  • --caller-route-and-additional-req: New caller route (JSON)
  • --asset-route-and-additional-req: New asset route (JSON)

Update Admin​

dchain tx notary update-admin [notary-info-id] [new-admin] --from [key]

Update the admin of NotaryInfo for a given NotaryInfoId (current admin only).

Example:

dchain tx notary update-admin 1 dchain1newadmin... --from mykey

Remove NotaryInfo​

dchain tx notary remove [notary-info-id] --from [key]

Remove the NotaryInfo for a given NotaryInfoId (admin only).

Example:

dchain tx notary remove 1 --from mykey

Set Currency Conversion Rate​

dchain tx notary set-currency-rate [currency] [rate] --from [key]

Set currency conversion rate to EUR (authority only).

Example:

dchain tx notary set-currency-rate USD 1.1 --from authority-key

Set EUR Price in Udt​

dchain tx notary set-eur-price [price] --from [key]

Set EUR price in udt (authority only).

Example:

dchain tx notary set-eur-price 250000000 --from authority-key

Set Notarisation Fee Rate​

dchain tx notary set-fee-rate [rate] --from [key]

Set notarisation fee rate for EUR equivalent (authority only).

Example:

dchain tx notary set-fee-rate 0.005 --from authority-key

Common CLI Flags​

All transaction commands support standard Cosmos SDK flags:

  • --from: Key name or address of transaction sender
  • --chain-id: Chain identifier
  • --fees: Transaction fees
  • --gas: Gas limit
  • --gas-prices: Gas prices
  • --node: Node RPC endpoint
  • --broadcast-mode: Transaction broadcasting mode (sync, async, block)

VCV Integration Notes​

When using the client APIs with VCV verification:

  1. Transaction ExtensionOptions: For messages that require caller verification (e.g., MsgNotarise), the transaction must include a verifiable presentation in the ExtensionOptions field. This is verified by the VCV AnteHandler before the transaction executes.

  2. Verifier Input: The verifier_input field in MsgNotarise contains a separate verifiable presentation used for asset verification during message execution.

  3. Route Validation: When registering or updating routes, the module validates that the referenced routes exist on verifier contracts via the x/vcv module.

  4. Error Handling: If VCV verification fails, transactions will be rejected with specific error messages indicating whether the failure occurred during caller verification (AnteHandler) or asset verification (keeper execution).

Proto Files​

Full proto definitions are available at:

  • Query service: proto/d/notary/v1/query.proto
  • Msg service: proto/d/notary/v1/tx.proto
  • Type definitions: proto/d/notary/v1/types.proto

Generated gRPC clients:

  • Query client: api/d/notary/v1/query_grpc.pb.go
  • Msg client: api/d/notary/v1/tx_grpc.pb.go