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

GetGlobalNotesForIssuer​

Retrieves all Global Notes issued by a specific issuer.

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

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

Request:

message QueryGetGlobalNotesForIssuerRequest {
  string issuer = 1;
}

Response:

message QueryGetGlobalNotesForIssuerResponse {
  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 issuer for a depository.

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

Request:

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

Response:

message MsgAddAuthorizedIssuerResponse {}

RemoveAuthorizedIssuer​

Removes an authorised issuer from a depository.

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

Request:

message MsgRemoveAuthorizedIssuer {
  string owner = 1;
  string depository_id = 2;
  string 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 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 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{
    Issuer:        "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 issuer
curl http://localhost:1317/d/depository/v1/global_notes/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 Issuer​

dchain query depository global-notes-for-issuer [issuer]

Get all Global Notes issued by an issuer.

Example:

dchain query depository global-notes-for-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] [issuer] --from [owner-key]

Authorise an issuer for a depository.

Example:

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

Remove Authorised Issuer​

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

Remove an authorised issuer.

Example:

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

Issue PT with Global Note​

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

Issue a Global Note and mint PT tokens. transferability is required and explicit — transferable or non-transferable (the CLI forms of TRANSFERABILITY_TRANSFERABLE / TRANSFERABILITY_NON_TRANSFERABLE); unspecified is rejected, so a PT can never be issued transferable by omission.

Example:

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

Issue frozen (non-transferable) and/or seed per-address restrictions:

dchain tx depository issue-pt 1 US1234567890 abc123... 1000000 1 "did:dchain:notary:xyz" non-transferable \
  --send-restrictions '{"address":"dchain1...","can_send":false,"can_receive":true}' \
  --from issuer

Surrender Global Note​

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

Surrender a Global Note and burn all PT tokens.

Example:

dchain tx depository surrender US1234567890 --from issuer

Set PT Transferability​

dchain tx depository set-pt-transferability [isin] [transferability] --from [issuer-key]

Set the transferability and per-address restrictions for a PT (issuer only). transferability is required and explicit (transferable or non-transferable) — an omitted value is rejected, so a restrictions-only edit can never silently unpause the PT. Restriction entries are passed via repeatable JSON flags.

Example:

dchain tx depository set-pt-transferability US1234567890 non-transferable \
  --upsert-restrictions '{"address":"dchain1...","can_send":false,"can_receive":true}' \
  --remove-restrictions dchain1... \
  --from issuer

Send and Set Transferability​

dchain tx depository send-and-set-transferability [isin] [transferability] --from [issuer-key]

Distribute PT to recipients and set transferability in one tx (issuer only). transferability is required and explicit; unspecified is rejected. Repeated fields are passed as JSON flags.

Example:

dchain tx depository send-and-set-transferability US1234567890 non-transferable \
  --outputs '{"recipient":"dchain1...","amount":"100"}' \
  --upsert-restrictions '{"address":"dchain1...","can_send":false,"can_receive":true}' \
  --from issuer

Set Depository Block List​

dchain tx depository set-depository-block-list [depository-id] --from [owner-key]

Upsert/remove depository block list entries (owner only). Entries are passed via repeatable JSON flags.

Example:

dchain tx depository set-depository-block-list 1 \
  --upsert-blocks '{"address":"dchain1...","block_send":true,"block_receive":false}' \
  --remove-blocks dchain1... \
  --from owner

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