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.

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;
}

The NotaryInfo holds the admin, the asset type id and the two x/vcv route ids. The verification routes themselves live natively in the x/vcv module (keyed by /d.notary.v1.MsgNotarise:content:<id> and /d.notary.v1.MsgNotarise:extop:<id>) and are queried through x/vcv, not through notary.

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")
}

GetEurPriceInAdt​

Retrieves how many adt equal 1 EUR.

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

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

Request:

message GetEurPriceInAdtRequest {}

Response:

message GetEurPriceInAdtResponse {
  string price = 1;  // Decimal string (e.g., "250000000000000000000" = 2.5e20 adt for 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;
}

GetAuthority​

Retrieves the module authority address (the account permitted to execute authority-gated messages).

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

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

Request:

message QueryGetAuthorityRequest {}

Response:

message QueryGetAuthorityResponse {
  string authority = 1;
}

Msg Service (Transactions)​

The Msg service handles state-changing operations. All transactions require proper signatures; notarisation additionally requires a valid verifiable presentation verified natively by x/vcv.

Package: d.notary.v1.Msg

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

Notarise​

Notarises an asset by providing a verifiable presentation verified natively by 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 (SD-JWT) for 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: During execution the keeper resolves the NotaryInfo's x/vcv route via VcvKeeper.GetRoute and verifies verifier_input against it with VcvKeeper.VerifyVerifiablePresentation, passing the computed AssetId and OdpHash as comparison values.

UpdateNotarisedAsset​

Updates the state of an existing notarised asset (owner or operator proxy only).

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

Request:

message MsgUpdateNotarisedAsset {
  string sender = 1;
  string notarised_asset_id = 2;
  bytes new_asset_data = 3;        // JSON-encoded AssetInvoiceUpdateData
}

Response:

message MsgUpdateNotarisedAssetResponse {
  string updated_notarised_asset_id = 1;
}

RegisterNotaryInfo​

Registers a new notary configuration for a DApp and provisions its native x/vcv route(s).

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

Request:

message RegisterNotaryRoute {
  string issuer = 1;
  d.vcv.v1.RouteType typ = 2;              // Currently only SD-JWT
  repeated d.vcv.v1.Requirement routes = 3;
  repeated d.vcv.v1.VerificationMaterial verification_materials = 4;
}

message MsgRegisterNotaryInfo {
  string sender = 1;
  string notary_info_admin = 2;            // Optional, defaults to sender
  uint64 asset_type_id = 3;
  RegisterNotaryRoute ext_opt_route = 4;   // Optional, verified by the vcv ante handler
  RegisterNotaryRoute content_route = 5;   // Required, verified during notarisation
}

Response:

message MsgRegisterNotaryInfoResponse {
  uint64 notary_info_id = 1;
  string notary_ext_opt_route_id = 2;
  string notary_content_route_id = 3;
}

VCV Integration: After storing the NotaryInfo, the keeper compiles each provided RegisterNotaryRoute into an x/vcv Route{Admin, Typ, Requirements, Issuers} and registers it via VcvKeeper.SetRoute under route id /d.notary.v1.MsgNotarise:extop:<notary_info_id> and/or /d.notary.v1.MsgNotarise:content:<notary_info_id>. Note that the keeper currently sets only notary_info_id in the response; the route id fields are left empty.

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 {}

SetEurPriceInAdt​

Sets the EUR price in adt (authority only).

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

Request:

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

Response:

message MsgSetEurPriceInAdtResponse {}

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.

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 Adt​

dchain query notary eur-price-in-adt

Get Notarisation Fee Rate​

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. The verifier-input is the verifiable presentation (SD-JWT) verified natively by x/vcv against the NotaryInfo's route.

Example:

dchain tx notary notarise 1 <verifier-input-hex> <asset-data-hex> --from mykey

Register NotaryInfo​

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

Register a new NotaryInfo and get a NotaryInfoId back. This also provisions the native x/vcv route(s) (the content route, and optionally an extension-option route) for the NotaryInfo.

Example:

dchain tx notary register 1 --from mykey

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 Adt​

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

Set EUR price in adt (authority only).

Example:

dchain tx notary set-eur-price 250000000000000000000 --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.01 --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 notarisation:

  1. Verifier Input: The verifier_input field in MsgNotarise carries the verifiable presentation (SD-JWT). During execution the notary keeper verifies it natively via x/vcv against the NotaryInfo's route.

  2. Route Provisioning: When registering a NotaryInfo, the content_route (and optionally the ext_opt_route) define the native x/vcv routes that future notarisations are verified against; they are stored in x/vcv under /d.notary.v1.MsgNotarise:content:<notary_info_id> and /d.notary.v1.MsgNotarise:extop:<notary_info_id>.

  3. Error Handling: If x/vcv verification fails, the Notarise transaction is rejected with an error wrapping the underlying verification failure.

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, proto/d/notary/v1/asset_invoice.proto
  • VCV route types: proto/d/vcv/v1/verifier.proto