Messages

Message Types

UpdateParams

Purpose: Update the x/depository module parameters (governance operation).

Sender: Must be the module authority (typically x/gov)

Parameters:

• authority: The address that controls the module
• params: New parameters to set
  • platform_admin: Address authorised to register depositories

Returns: MsgUpdateParamsResponse (empty)

---

RegisterDepository

Purpose: Register a new depository that can custody Global Notes.

Sender: Must be the platform admin (from module params)

Parameters:

• admin: Platform admin address (signer)
• owner: Address that will own and manage the depository
• pauser: Address that can pause/unpause the depository
• region: Geographic region identifier

Authorization:

• Only the platform_admin from module params can register depositories

Returns:

message MsgRegisterDepositoryResponse {
  string depository_id = 1;
}

---

UpdateDepositoryParams

Purpose: Update depository owner and/or pauser addresses.

Sender: Must be the current owner of the depository

Parameters:

• owner: Current owner address (signer)
• depository_id: ID of the depository to update
• new_owner: New owner address (optional, empty string = no change)
• new_pauser: New pauser address (optional, empty string = no change)

Authorization:

• Only the current owner of the depository can update parameters

Returns: MsgUpdateDepositoryParamsResponse (empty)

---

PauseDepository

Purpose: Pause all operations on a depository.

Sender: Must be the pauser of the depository

Parameters:

• pauser: Pauser address (signer)
• depository_id: ID of the depository to pause

Effects:

• Sets depository.paused = true
• Blocks IssuePTWithGlobalNote and SurrenderGlobalNote operations

Authorization:

• Only the pauser of the depository can pause it

Returns: MsgPauseDepositoryResponse (empty)

---

UnpauseDepository

Purpose: Resume operations on a paused depository.

Sender: Must be the pauser of the depository

Parameters:

• pauser: Pauser address (signer)
• depository_id: ID of the depository to unpause

Effects:

• Sets depository.paused = false
• Re-enables IssuePTWithGlobalNote and SurrenderGlobalNote operations

Authorization:

• Only the pauser of the depository can unpause it

Returns: MsgUnpauseDepositoryResponse (empty)

---

AddAuthorizedIssuer

Purpose: Authorise an issuer to issue Global Notes under a depository.

Sender: Must be the owner of the depository

Parameters:

• owner: Depository owner address (signer)
• depository_id: ID of the depository
• issuer: Address of the issuer to authorise

Effects:

• Adds entry to AuthorisedIssuers mapping: (depository_id, issuer) → true

Authorization:

• Only the owner of the depository can authorise issuers

Errors:

• ErrIssuerAlreadyAuthorised: If the issuer is already authorised

Returns: MsgAddAuthorizedIssuerResponse (empty)

---

RemoveAuthorizedIssuer

Purpose: Remove authorisation from an issuer.

Sender: Must be the owner of the depository

Parameters:

• owner: Depository owner address (signer)
• depository_id: ID of the depository
• issuer: Address of the issuer to remove

Effects:

• Sets entry in AuthorisedIssuers mapping: (depository_id, issuer) → false

Authorization:

• Only the owner of the depository can remove issuers

Errors:

• ErrIssuerNotAuthorised: If the issuer is not currently authorised

Returns: MsgRemoveAuthorizedIssuerResponse (empty)

---

IssuePTWithGlobalNote

Purpose: Issue a Global Note and mint corresponding PT tokens.

Sender: Must be an authorised issuer for the depository

Parameters:

• issuer: issuer address (signer)
• depository_id: ID of the custodian depository
• isin: International Securities Identification Number (unique)
• global_note_hash: Hash of the underlying asset data
• total_supply: Number of PT tokens to mint
• asset_type_id: Links to x/notary asset type
• notarised_asset_id: Links to the notarised asset in x/notary
• transferability: Required, explicit — TRANSFERABILITY_TRANSFERABLE or TRANSFERABILITY_NON_TRANSFERABLE. TRANSFERABILITY_UNSPECIFIED (the omitted/zero value) is rejected with ErrTransferabilityUnspecified, so a PT can never be issued transferable by omission; the transfer setting is an explicit issuance-time decision.
• send_restrictions: Optional initial per-address PtSendRestriction records (empty = unrestricted)

Effects:

1. Creates InternalGlobalNote record
2. Creates PTDenom record with ISIN and total supply
3. Initialises PtTransferability from the supplied transferability setting (NON_TRANSFERABLE → paused = true) and writes any send_restrictions records
4. Mints total_supply PT tokens to the module account
5. Transfers all PT tokens to the issuer

Authorization:

• issuer must be authorised for the depository
• Depository must not be paused

Validation:

• total_supply must be positive
• transferability must be explicitly TRANSFERABLE or NON_TRANSFERABLE (enforced in ValidateBasic and the handler)
• ISIN must be unique (no existing Global Note with same ISIN)

Errors:

• ErrDepositoryNotFound: Depository doesn't exist
• ErrDepositoryPaused: Depository is paused
• ErrIssuerNotAuthorised: issuer not authorised
• ErrInvalidAmount: Total supply is zero or negative
• ErrTransferabilityUnspecified: transferability omitted or TRANSFERABILITY_UNSPECIFIED
• ErrGlobalNoteAlreadyExists: ISIN already used

Returns:

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

---

SurrenderGlobalNote

Purpose: Surrender a Global Note at maturity, burning all PT tokens.

Sender: Must be the original issuer of the Global Note

Parameters:

• issuer: issuer address (signer)
• isin: ISIN of the Global Note to surrender

Effects:

1. Retrieves all PT token holders and their balances
2. Transfers all PT tokens from holders to module account
3. Burns all PT tokens
4. Updates PTDenom.TotalSupply to zero
5. Records final holder balances in response

Authorization:

• Only the original issuer of the Global Note can surrender it
• Associated depository must not be paused

Error Handling:

• If any transfer fails, all successful transfers are rolled back
• Balance restoration is logged if rollback fails

Errors:

• ErrGlobalNoteNotFound: Global Note doesn't exist
• ErrDepositoryNotFound: Associated depository doesn't exist
• ErrDepositoryPaused: Depository is paused
• ErrUnauthorized: Sender is not the original issuer
• ErrPTDenomSurrenderFailed: Total supply mismatch during surrender

Returns:

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

The latest_pt_holders contains the final balances of all PT holders before burning, useful for off-chain settlement.

---

SetPTTransferability

Purpose: Set the transferability and per-address send restrictions of a PT.

Sender: Must be the issuer recorded on the PT's Global Note

Parameters:

• issuer: issuer address (signer)
• isin: ISIN identifying the Global Note / PT
• transferability: New transfer setting (always applied). Required, explicit — TRANSFERABILITY_UNSPECIFIED is rejected, so a caller editing only the per-address restrictions cannot silently unpause the PT.
• upsert_restrictions: PtSendRestriction records to add or update
• remove_restrictions: Addresses whose restriction records are deleted (back to unrestricted)

Effects:

• Sets PtTransferability.paused for the PT denom (NON_TRANSFERABLE → paused = true)
• Upserts / removes the corresponding PtSendRestriction records

Authorization:

• Signer must be the issuer bound to the PT's Global Note. This is intentionally not the depository's AuthorizedIssuers list — only the note's own issuer may retune its PT.
• Not gated on depository pause: the issuer can adjust transferability even while the depository is paused.

Returns: MsgSetPTTransferabilityResponse (empty)

---

SendAndSetTransferability

Purpose: Atomically distribute PT to recipients and set its transferability in a single transaction, so the issuer can send to investors and lock the token together.

Sender: Must be the issuer recorded on the PT's Global Note

Parameters:

• issuer: issuer address (signer)
• isin: ISIN identifying the Global Note / PT
• outputs: Distribution legs (SendOutput recipient/amount pairs), sent from the issuer's balance before the transferability update is applied
• transferability: New transfer setting applied after the sends. Required, explicit — TRANSFERABILITY_UNSPECIFIED is rejected.
• upsert_restrictions: PtSendRestriction records to add or update
• remove_restrictions: Addresses whose restriction records are deleted

Effects:

1. Distributes PT issuer → module account → recipients
2. Applies the transferability setting and restriction changes atomically

Authorization:

• Same signer rule as SetPTTransferability: the issuer bound to the Global Note (not the AuthorizedIssuers list).
• Is gated on depository pause: because it moves PT, it is blocked while the depository is paused. (SetPTTransferability, which only edits controls without moving tokens, is not gated — this is the deliberate asymmetry.)

Returns:

message MsgSendAndSetTransferabilityResponse {
  string pt_denom = 1;
}

---

SetDepositoryBlockList

Purpose: Upsert or remove entries of the per-depository address block list, enforced across all PTs of the depository.

Sender: Must be the owner of the depository

Parameters:

• owner: depository owner address (signer)
• depository_id: ID of the depository
• upsert_blocks: DepositoryBlockEntry records to add or update
• remove_blocks: Addresses whose block entries are deleted

Effects:

• Upserts / removes DepositoryBlockEntry records keyed by (depository_id, address)

Authorization:

• Only the owner of the depository can manage its block list

Returns: MsgSetDepositoryBlockListResponse (empty)

Authorization Summary

Message	Authorised Sender
UpdateParams	Module authority (x/gov)
RegisterDepository	Platform admin
UpdateDepositoryParams	Depository owner
PauseDepository	Depository pauser
UnpauseDepository	Depository pauser
AddAuthorizedIssuer	Depository owner
RemoveAuthorizedIssuer	Depository owner
IssuePTWithGlobalNote	Authorised issuer
SurrenderGlobalNote	Original issuer of the note
SetPTTransferability	Issuer bound to the note
SendAndSetTransferability	Issuer bound to the note
SetDepositoryBlockList	Depository owner