Skip to main content

Client

The x/depository 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 depository module state.

Package: d.depository.v1.Query

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

GetParams​

Retrieves the module parameters.

gRPC Method: /d.depository.v1.Query/GetParams

REST Endpoint: GET /d/depository/v1/params

Request:

message QueryGetParamsRequest {}

Response:

message QueryGetParamsResponse {
  Params params = 1;
}

GetDepository​

Retrieves a specific depository by its ID.

gRPC Method: /d.depository.v1.Query/GetDepository

REST Endpoint: GET /d/depository/v1/depository/{id}

Request:

message QueryGetDepositoryRequest {
  string id = 1;
}

Response:

message QueryGetDepositoryResponse {
  Depository depository = 1;
}

GetGlobalNoteByISIN​

Retrieves a Global Note by its ISIN.

gRPC Method: /d.depository.v1.Query/GetGlobalNoteByISIN

REST Endpoint: GET /d/depository/v1/global_note/{isin}

Request:

message QueryGetGlobalNoteByISINRequest {
  string isin = 1;
}

Response:

message QueryGetGlobalNoteByISINResponse {
  GlobalNote global_note = 1;
}

GetGlobalNotesForSpvIssuer​

Retrieves all Global Notes issued by a specific SPV issuer.

gRPC Method: /d.depository.v1.Query/GetGlobalNotesForSpvIssuer

REST Endpoint: GET /d/depository/v1/global_notes/spv_issuer/{spv_issuer}

Request:

message QueryGetGlobalNotesForSpvIssuerRequest {
  string spv_issuer = 1;
}

Response:

message QueryGetGlobalNotesForSpvIssuerResponse {
  repeated GlobalNote global_notes = 1;
}

GetDenomWithIsin​

Retrieves the PT denom string for a given ISIN.

gRPC Method: /d.depository.v1.Query/GetDenomWithIsin

REST Endpoint: GET /d/depository/v1/denom/{isin}

Request:

message QueryGetDenomWithIsinRequest {
  string isin = 1;
}

Response:

message QueryGetDenomWithIsinResponse {
  string denom = 1;
}

Msg Service (Transactions)​

The Msg service handles state-changing operations. All transactions require proper signatures.

Package: d.depository.v1.Msg

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

UpdateParams​

Updates the module parameters (governance operation).

gRPC Method: /d.depository.v1.Msg/UpdateParams

Request:

message MsgUpdateParams {
  string authority = 1;
  Params params = 2;
}

Response:

message MsgUpdateParamsResponse {}

RegisterDepository​

Registers a new depository.

gRPC Method: /d.depository.v1.Msg/RegisterDepository

Request:

message MsgRegisterDepository {
  string admin = 1;
  string owner = 2;
  string pauser = 3;
  string region = 4;
}

Response:

message MsgRegisterDepositoryResponse {
  string depository_id = 1;
}

UpdateDepositoryParams​

Updates depository parameters (owner/pauser).

gRPC Method: /d.depository.v1.Msg/UpdateDepositoryParams

Request:

message MsgUpdateDepositoryParams {
  string owner = 1;
  string depository_id = 2;
  string new_owner = 3;
  string new_pauser = 4;
}

Response:

message MsgUpdateDepositoryParamsResponse {}

PauseDepository​

Pauses a depository.

gRPC Method: /d.depository.v1.Msg/PauseDepository

Request:

message MsgPauseDepository {
  string pauser = 1;
  string depository_id = 2;
}

Response:

message MsgPauseDepositoryResponse {}

UnpauseDepository​

Unpauses a depository.

gRPC Method: /d.depository.v1.Msg/UnpauseDepository

Request:

message MsgUnpauseDepository {
  string pauser = 1;
  string depository_id = 2;
}

Response:

message MsgUnpauseDepositoryResponse {}

AddAuthorizedIssuer​

Authorises an SPV issuer for a depository.

gRPC Method: /d.depository.v1.Msg/AddAuthorizedIssuer

Request:

message MsgAddAuthorizedIssuer {
  string owner = 1;
  string depository_id = 2;
  string spv_issuer = 3;
}

Response:

message MsgAddAuthorizedIssuerResponse {}

RemoveAuthorizedIssuer​

Removes an authorised SPV issuer from a depository.

gRPC Method: /d.depository.v1.Msg/RemoveAuthorizedIssuer

Request:

message MsgRemoveAuthorizedIssuer {
  string owner = 1;
  string depository_id = 2;
  string spv_issuer = 3;
}

Response:

message MsgRemoveAuthorizedIssuerResponse {}

IssuePTWithGlobalNote​

Issues a Global Note and mints PT tokens.

gRPC Method: /d.depository.v1.Msg/IssuePTWithGlobalNote

Request:

message MsgIssuePTWithGlobalNote {
  string spv_issuer = 1;
  string depository_id = 2;
  string isin = 3;
  string global_note_hash = 4;
  string total_supply = 5;
  uint64 asset_type_id = 6;
  string notarised_asset_id = 7;
}

Response:

message MsgIssuePTWithGlobalNoteResponse {
  GlobalNote global_note = 1;
  string pt_denom = 2;
}

SurrenderGlobalNote​

Surrenders a Global Note and burns all PT tokens.

gRPC Method: /d.depository.v1.Msg/SurrenderGlobalNote

Request:

message MsgSurrenderGlobalNote {
  string spv_issuer = 1;
  string isin = 2;
}

Response:

message MsgSurrenderGlobalNoteResponse {
  cosmos.base.v1beta1.Coin total_burnt = 1;
  LatestPtHolders latest_pt_holders = 2;
}

gRPC Client Examples​

Go gRPC Client​

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

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

// Get depository
resp, err := queryClient.GetDepository(context.Background(), &depositoryv1.QueryGetDepositoryRequest{
    Id: "1",
})

// Get Global Note by ISIN
gnResp, err := queryClient.GetGlobalNoteByISIN(context.Background(), &depositoryv1.QueryGetGlobalNoteByISINRequest{
    Isin: "US1234567890",
})

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

resp, err := msgClient.IssuePTWithGlobalNote(context.Background(), &depositoryv1.MsgIssuePTWithGlobalNote{
    SpvIssuer:        "dchain1...",
    DepositoryId:     "1",
    Isin:             "US1234567890",
    GlobalNoteHash:   "abc123...",
    TotalSupply:      "1000000",
    AssetTypeId:      1,
    NotarisedAssetId: "did:dchain:notary:...",
})

REST API Examples​

# Query module params
curl http://localhost:1317/d/depository/v1/params

# Query depository
curl http://localhost:1317/d/depository/v1/depository/1

# Query Global Note by ISIN
curl http://localhost:1317/d/depository/v1/global_note/US1234567890

# Query Global Notes by SPV issuer
curl http://localhost:1317/d/depository/v1/global_notes/spv_issuer/dchain1abc...

# Query PT denom for ISIN
curl http://localhost:1317/d/depository/v1/denom/US1234567890

CLI Commands​

The x/depository module provides CLI commands for both querying state and submitting transactions.

Query Commands​

All query commands are prefixed with query depository:

Get Params​

dchain query depository params

Get the module parameters.

Get Depository​

dchain query depository depository [id]

Get a depository by its ID.

Example:

dchain query depository depository 1

Get Global Note by ISIN​

dchain query depository global-note [isin]

Get a Global Note by its ISIN.

Example:

dchain query depository global-note US1234567890

Get Global Notes by SPV Issuer​

dchain query depository global-notes-by-issuer [spv-issuer]

Get all Global Notes issued by an SPV issuer.

Example:

dchain query depository global-notes-by-issuer dchain1abc...

Get PT Denom by ISIN​

dchain query depository denom [isin]

Get the PT denom string for an ISIN.

Example:

dchain query depository denom US1234567890

Transaction Commands​

All transaction commands are prefixed with tx depository:

Register Depository​

dchain tx depository register [owner] [pauser] [region] --from [admin-key]

Register a new depository (platform admin only).

Example:

dchain tx depository register dchain1owner... dchain1pauser... "EU" --from platform-admin

Update Depository Params​

dchain tx depository update-params [depository-id] --new-owner [addr] --new-pauser [addr] --from [owner-key]

Update depository owner and/or pauser.

Example:

dchain tx depository update-params 1 --new-owner dchain1newowner... --from owner

Pause Depository​

dchain tx depository pause [depository-id] --from [pauser-key]

Pause a depository.

Example:

dchain tx depository pause 1 --from pauser

Unpause Depository​

dchain tx depository unpause [depository-id] --from [pauser-key]

Unpause a depository.

Example:

dchain tx depository unpause 1 --from pauser

Add Authorised Issuer​

dchain tx depository add-issuer [depository-id] [spv-issuer] --from [owner-key]

Authorise an SPV issuer for a depository.

Example:

dchain tx depository add-issuer 1 dchain1spv... --from owner

Remove Authorised Issuer​

dchain tx depository remove-issuer [depository-id] [spv-issuer] --from [owner-key]

Remove an authorised SPV issuer.

Example:

dchain tx depository remove-issuer 1 dchain1spv... --from owner

Issue PT with Global Note​

dchain tx depository issue [depository-id] [isin] [global-note-hash] [total-supply] [asset-type-id] [notarised-asset-id] --from [spv-key]

Issue a Global Note and mint PT tokens.

Example:

dchain tx depository issue 1 US1234567890 abc123... 1000000 1 "did:dchain:notary:xyz" --from spv-issuer

Surrender Global Note​

dchain tx depository surrender [isin] --from [spv-key]

Surrender a Global Note and burn all PT tokens.

Example:

dchain tx depository surrender US1234567890 --from spv-issuer

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)

Proto Files​

Full proto definitions are available at:

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

Generated gRPC clients:

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