x/alias

Transactions

MsgAppointRegulator

/blockchain.alias.v1.MsgAppointRegulator

Signed by the authority field.

AppointRegulator names the authority holding the viewing key for a country.

MsgGrantAuditor

/blockchain.alias.v1.MsgGrantAuditor

Signed by the authority field.

GrantAuditor grants the time-boxed cross-account reading role.

MsgGrantRole

/blockchain.alias.v1.MsgGrantRole

Signed by the authority field.

GrantRole grants a role inside one jurisdiction. Governance, or the foundation for a country; governance alone for the chain-wide scope.

MsgRegisterAlias

/blockchain.alias.v1.MsgRegisterAlias

Signed by the account field.

RegisterAlias issues an identifier to the sending account.

MsgRegisterViewingKey

/blockchain.alias.v1.MsgRegisterViewingKey

Signed by the account field.

RegisterViewingKey publishes the sender's X25519 public key, or rotates it.

MsgRevokeRole

/blockchain.alias.v1.MsgRevokeRole

Signed by the authority field.

RevokeRole removes one such grant. The same signers as GrantRole.

MsgRevokeViewingKey

/blockchain.alias.v1.MsgRevokeViewingKey

Signed by the account field.

RevokeViewingKey marks one of the sender's key versions compromised.

MsgRotateAlias

/blockchain.alias.v1.MsgRotateAlias

Signed by the account field.

RotateAlias retires the sender's identifier and issues a new one.

MsgSetJurisdiction

/blockchain.alias.v1.MsgSetJurisdiction

Signed by the recorder field.

SetJurisdiction records or corrects the country an account belongs to.

MsgUpdateParams

/blockchain.alias.v1.MsgUpdateParams

Signed by the authority field.

UpdateParams sets the module parameters. Governance only.

It no longer appoints anybody. Appointing a foundation administrator is now MsgGrantRole with ROLE_FOUNDATION_ADMINISTRATOR and the chain-wide scope — which is still governance and nobody else, because a chain-wide grant is governance's alone, so the authority behind the act did not move. What moved is where it is recorded, and that is the point: the appointment and the role registry are one mechanism rather than two lists that happened to share a name.

Three failure modes went with the parameter, and they are worth recording because they are what the move was for. This message REPLACES THE WHOLE Params OBJECT — it is a message, not a field mask — so a proposal composed without reading the current parameters first silently dropped every administrator already appointed, and nothing caught it, because a list shorter than the one before it is a valid list; a grant cannot be dropped by a message about something else. Validate() never checked that an entry was an address, so a mistyped one passed a vote, occupied one of the eight places and granted the exemption to nobody, where MsgGrantRole decodes the holder. And an administrator was a bare address, where a role holder must be an x/group account, so the exemption is now held M-of-N like every other authority.

What remains here is payload_length. A value that reads back as 0 means the value is UNKNOWN, not zero — proto3 cannot tell a zero from a field nobody filled in, and Validate() refuses a zero, so no chain holds one. Resubmitting a guess would re-parameterise the chain.

Queries

Alias

GET /yamale/blockchain/alias/v1/alias/{id}

Alias resolves an identifier to an address. The hot path.

Request:

Response:

AliasOf

GET /yamale/blockchain/alias/v1/alias_of/{address}

AliasOf returns the identifier held by an address, for interfaces that need to show a person their own handle.

Request:

Response:

Auditors

GET /yamale/blockchain/alias/v1/auditors

Auditors lists the grants that have not expired, with their current keys.

A list endpoint in a module that avoids them, and it is the right call here: who may read across accounts is a fact the people being read about are entitled to see, and a sender cannot build a correct envelope without the whole set.

Response:

ChainWideGrants

GET /yamale/blockchain/alias/v1/chain_wide_grants

ChainWideGrants lists every grant whose scope is "*".

Its own endpoint, taking no argument, precisely because the chain-wide scope is the exception. An exception that can only be found by knowing to ask for the wildcard is an exception nobody audits, so a governance console can put this on a page and show the whole set of accounts that are not bounded by any border.

Response:

Jurisdiction

GET /yamale/blockchain/alias/v1/jurisdiction/{address}

Jurisdiction reports the country recorded against one account.

Request:

Response:

Params

GET /yamale/blockchain/alias/v1/params

Params returns the module parameters.

Response:

PayloadReaders

GET /yamale/blockchain/alias/v1/payload_readers/{country}

PayloadReaders lists every account entitled to be sealed into the encrypted payload of a payment that settles in one country, with the key each of them reads through.

This is what makes ROLE_SUPERVISOR a role rather than a name in a registry. A grant of it covering a country is an entitlement to read that country's payment detail, and the entitlement is realised by a sender wrapping the content key to the holder — so the set has to be resolvable in one call, at the moment of sending, from the chain rather than from a list somebody maintains beside it.

Two sources, one answer. The appointed regulator of the country is here because that is the authority with standing to act on the payment; every holder of ROLE_SUPERVISOR covering the country is here because oversight is what the role is. A chain-wide supervisor appears for every country, which is what a chain-wide grant means and why it is listed on its own endpoint for anyone auditing the exceptions.

Deliberately NOT here: the auditors. They are time-boxed, chain-wide and unrelated to any settlement jurisdiction, and folding them in would put an expiry rule in two responses that could come to disagree — see Auditors, which a sender calls as well. A complete envelope is this set plus that one plus the payer and the payee.

An empty response is a real answer: a country with no appointed regulator and no supervisor has nobody entitled to read, and the payment is readable by its two parties and any live auditor. It is not an error and a sender must not retry it.

Request:

Response:

Perimeter

GET /yamale/blockchain/alias/v1/perimeter/{country}

Perimeter lists the accounts recorded in one country, so an authority can see the accounts it may act on and no others.

This is a list endpoint in a module that deliberately has none, so note what it returns and what it does not: jurisdiction records, never identifiers. Walking it tells you which addresses are recorded in a country — a supervisory fact, and the reason the endpoint exists — and gives no shortcut to the alias directory that is withheld above.

Request:

Response:

Regulator

GET /yamale/blockchain/alias/v1/regulator/{country}

Regulator returns the authority appointed over one country, with its current viewing key.

Both in one response because the sender needs both and asking separately invites the half-answer: an appointment resolved, a key not fetched, and an envelope built without the regulator on it that looks complete.

Request:

Response:

Retired

GET /yamale/blockchain/alias/v1/retired/{id}

Retired reports whether an identifier has been tombstoned. A client that resolves nothing should be able to tell "never existed" from "existed and was retired", because those mean very different things to somebody about to send money.

Request:

Response:

RoleGrants

GET /yamale/blockchain/alias/v1/role_grants/{holder}

RoleGrants lists every role one account holds, and where.

The question an operator actually asks about a key before trusting it, and the question a holder asks to find out what the chain thinks they may do. Empty is a real answer: an account with no grants may act nowhere.

Request:

Response:

RoleHolders

GET /yamale/blockchain/alias/v1/role_holders/{jurisdiction}

RoleHolders lists who holds roles inside one jurisdiction.

The supervisory view: "who may act on my country's accounts". Chain-wide grants are deliberately not folded in — they are listed on their own endpoint — because a country's own list should show what that country granted, and silently mixing in the chain-wide exceptions would hide them among the ordinary entries of every country at once.

Request:

Response:

ViewingKeys

GET /yamale/blockchain/alias/v1/viewing_keys/{address}

ViewingKeys returns every version of one account's viewing key, newest first.

Every version, not just the live one, because a payload encrypted last year is wrapped to the key that was live last year. A client that could only fetch the current key would report an old but perfectly readable payment as undecryptable, which is the failure the version field exists to prevent.

Request:

Response:

State

Alias

Alias binds one identifier to one address, permanently.

One name, one address. One identifier per address. Neither is ever repointed — an alias can be retired, and a retired identifier is never issued again, but it cannot be made to resolve somewhere else. That is the property a payment handle needs: an identifier somebody memorised last year either still means what it meant, or it means nothing.

AuditorEntitlement

AuditorEntitlement pairs a grant with the key it reads through.

AuditorGrant

AuditorGrant is the time-boxed role that may read payment payloads across accounts, for aggregate checks no single party's own keys can perform.

It expires by itself. A grant that has to be revoked to end is a grant that stays live when the person who would have revoked it moves on, and this one reads the detail of payments belonging to people who never dealt with the holder — so the failure mode of forgetting is the whole population's remittance text, indefinitely.

Jurisdiction

Jurisdiction is the national perimeter an account belongs to.

It lives here rather than in x/paymsg because every module that has to refuse an out-of-perimeter action — the land registry, enforcement, stablecoin issuance — would otherwise have to ask the payments module where an account is. A perimeter that only exists for accounts that happen to be somebody's payment customer is not a perimeter: validators, registry offices and treasury signers are none of those, and each one would sit in the unclaimed state the whole design exists to remove.

It is recorded by the participant that onboarded the account, never self-declared, and changed only by a foundation administrator. That is what makes it evidence rather than a preference.

OfficeShape

OfficeShape is an M-of-N, written down before the ceremony and held to afterwards.

Both numbers are FLOORS, not equalities, and the asymmetry is the design. Adding a member to an office is fine: a three-of-five that becomes a three-of-six is more people, not fewer, and refusing it would mean an office could never grow without the foundation re-granting its roles. Dropping below either number is not fine, and it is the same rule the constitution applies to the foundation's own group, for the same reason: three-of-five becoming three-of-four moves sixty per cent to seventy-five and walks towards unanimity, where one unreachable member freezes the office; and a threshold falling to one is the single key the whole arrangement exists to abolish.

What it does NOT constrain is an office tightening itself. An office that votes three-of-five up to five-of-five satisfies both floors and can then be frozen by one absent member — which is self-harm rather than capture, and a rule that refused it would be a rule stopping an office from being more careful than it was asked to be.

PayloadReader

PayloadReader is one account entitled to open a country's payment payloads, and the reason it is entitled.

RegulatorAppointment

RegulatorAppointment names the authority that holds the third viewing key over every payment declaring one country as its settlement jurisdiction.

One per country, deliberately. The settlement jurisdiction is the field that settles which authority may act on a cross-border payment, and a country with two appointed regulators would reintroduce exactly the contest over standing that the single declaration exists to end.

RoleGrant

RoleGrant is the triple the whole perimeter is built from: who, what role, where.

It is created and removed by governance and by nobody else. A role its own holder could grant is not a perimeter, and neither is one another holder of the same role could hand out — buying one office would buy the power to manufacture the rest.

ViewingKey

ViewingKey is the X25519 public key a payment payload is encrypted to.

It lives in this module for the same reason the jurisdiction does. The payload is encrypted at the moment the payment is sent, so the sender has to be able to look up every recipient's key then — the payer's, the payee's, the key of the regulator of the declared settlement jurisdiction, and every live auditor's. A registry that only covered accounts which happen to be somebody's payment customer would leave the regulator and the auditor unresolvable, which are two of the three parties the design exists to serve.

Only the public half is ever recorded. That is not a convention that could be relaxed later: a private key on an append-only ledger is a private key published to everyone forever, and there is no erasure path that takes it back.

Value types

PayloadReaderBasis

PayloadReaderBasis is why an account may read a country's payment payloads.

Role

Role is a power an account may be granted inside a perimeter.

The list is short and closed on purpose. A role is only worth having if some module refuses an action without it, so a role nothing consults is a name in a registry pretending to be a control — and the way that happens is by letting the set grow faster than the checks.

Errors

Every way a transaction to this module can be rejected.