Signer Protocol

Signer interface — AWS KMS, local key, and remote signer implementations

Signer Protocol

This document covers the entire signer infrastructure of the QTG v3 movement orchestration framework. It includes the protocol interface, data model, implementations, binding resolution, the signing flow inside dispatch, registry/health synchronization, CCTP caller-address validation, the private AWS KMS signer service, and the remote proxy.

Source of truth:

• src/qtg/domain/protocols.py — SignerProtocol, SignRequest, SignResult, SigningIntent
• src/qtg/infrastructure/signers/ — noop, aws_kms_evm, remote_proxy, local_private_key_evm, registry
• src/qtg/application/services/dispatch.py — signing flow
• src/qtg/application/services/signing_jobs.py — durable one-use movement job/result contract
• src/qtg/application/services/message_signing.py — strict SIWE message jobs and explicit attempts
• src/qtg/application/services/registry.py — health sync
• src/qtg/application/services/signer_metadata.py — caller verification
• src/qtg/infrastructure/db/models.py — SignerRegistryEntry

Current snapshot

• There are currently four signer implementations.
  1. NoopSigner
  2. AwsKmsEvmSigner — runs in the private signer service or an explicit one-off tool
  3. RemoteSignerProxy — the only signer implementation accepted by qtg.main
  4. LocalPrivateKeySignerEvm — development-only explicit-tool path (Tier-3)
• The EVM signer-required runtime path is Core RemoteSignerProxy -> private AwsKmsEvmSigner service -> AWS KMS.
• qtg.main rejects every non-empty MG_LOCAL_SIGNER_BACKEND/_KEY/_KMS_KEY_ID/_AWS_REGION/_AWS_PROFILE/_AWS_ENDPOINT_URL/_KEY_SOURCE/_KEY_REF field and MG_EXTRA_SIGNERS_JSON; explicit operator tools retain those direct inputs.
• LocalPrivateKeySignerEvm is for local evaluation / dev only — see local-private-key-signer.md. Do not use it for production fund movement.

---

1. SignerProtocol Interface

@runtime_checkable protocol defined in domain/protocols.py.

@runtime_checkable
class SignerProtocol(Protocol):
    signer_key: str

    async def sign(self, request: SignRequest) -> SignResult: ...
    async def health(self) -> dict[str, Any] | None: ...

Method description

Method	Role	Return
sign(request)	Receives a signing request and returns the signing result	SignResult
health()	Returns signer status and metadata	dict or None

Core properties

• signer_key: unique identifier inside the registry. Referenced from the node’s signer_binding dict.
• runtime_checkable: type checks are possible with isinstance(obj, SignerProtocol).

health() contract

For an EVM signer, health() may include a signer_address value. Registry health refresh validates and normalizes it, then writes it only to observed_signer_address; it is not the operator-pinned identity and is not copied into capabilities.

{
    "ok": True,
    "signer_key": "signer.cctp.mainnet",
    "signer_address": "0x1234567890abcdef1234567890abcdef12345678",
    "chain_families": ["evm"],
    "version": "1.2.0"
}

Optional SignerIdentityProtocol

EVM signers that support operator enrollment also implement the optional, runtime-checkable SignerIdentityProtocol:

@runtime_checkable
class SignerIdentityProtocol(Protocol):
    async def resolve_signer_identity(self, *, fresh: bool) -> str | None: ...

The enrollment endpoint resolves this value with fresh=True, requires a nonzero canonical EVM address, and compares it with the submitted expected address. KMS and identity-capable remote adapters may implement the protocol; signer-free and non-EVM adapters simply do not, so identity enrollment is unavailable rather than guessed.

---

2. Signing intents

SignRequest.signing_intent is a three-variant union (SigningIntent | MessageSigningIntent | HyperliquidApproveAgentIntent). Movement callers use SigningIntent; strict SIWE message jobs use MessageSigningIntent; browser typed-data jobs (Hyperliquid approve-agent, JEP KMS-wallet opt-in) use HyperliquidApproveAgentIntent. The signer rejects a payload format whose intent variant does not match.

Movement SigningIntent

This is the movement signing-intent declaration passed to the signer. It allows the signer to verify in a human-readable form “what is being signed.”

class SigningIntent(BaseModel):
    action: str
    asset: str
    amount: str
    destination: str
    max_fee_usd: str | None = None
    chain_family: str
    allowed_payload_hash: str

Field details

Field	Type	Source	Description
action	str	PreparedAction.action_type	action type selected by the executor
asset	str	ExecutionContext.intent["asset"]	identifier of the asset being moved
amount	str	ExecutionContext.intent["amount"] or input_params["amount"]	transfer amount
destination	str	ExecutionContext.intent["destination"]	destination address or identifier
max_fee_usd	str | None	currently always None	maximum fee in USD terms
chain_family	str	ExecutionContext.input_params["chain_family"] (default: "evm")	chain family being signed for
allowed_payload_hash	str	PreparedAction.payload_hash	hash of the payload being signed

Security role of intent

SigningIntent exists to prevent blind signing. The signer should compare at least the following two:

1. the intent’s action, asset, amount, destination
2. allowed_payload_hash and the actual payload hash

Message MessageSigningIntent

The message variant is intentionally narrower than generic personal_sign:

class MessageSigningIntent(BaseModel):
    intent_type: Literal["message"] = "message"
    method: Literal["personal_sign"]
    message_kind: Literal["siwe_v1"]
    account_ref: str
    origin: str
    chain_id: int
    message_sha256: str
    eip191_digest: str
    allowed_payload_hash: str

Core builds this intent only after validating exact canonical EIP-4361 SIWE bytes against an active policy bound to one OIDC credential, principal, account, HTTPS origin, and chain. The private signer receives those original bytes as canonical base64: and independently recomputes both SHA-256 payload binding and the EIP-191 version 0x45 digest before KMS I/O. It does not accept an opaque caller-supplied digest.

---

3. SignRequest

This is the full signing request passed to the signer by combining the PreparedAction returned from executor.prepare() with ExecutionContext.

class SignRequest(BaseModel):
    protocol_version: str
    request_id: str
    request_node_id: str
    signing_job_id: str = Field(min_length=1)
    attempt_no: int = Field(ge=1)
    signing_intent: SigningIntent
    payload_format: str
    payload: str
    payload_hash: str
    metadata: dict[str, Any] = Field(default_factory=dict)

Field details

Field	Type	Source	Description
protocol_version	str	ExecutionContext.protocol_version	v3 protocol version
request_id	str	ExecutionContext.request_id	movement request UUID
request_node_id	str	ExecutionContext.request_node_id	request node UUID
signing_job_id	str	durable signing_jobs.id	one-use job identity; required on the wire
attempt_no	positive int	durable attempt row	movement signing is fixed to attempt 1; message jobs permit explicit attempts 1–3
signing_intent	SigningIntent | MessageSigningIntent | HyperliquidApproveAgentIntent	trusted Core service	see the section above
payload_format	str	PreparedAction.payload_format	payload format identifier
payload	str	PreparedAction.payload	raw payload being signed
payload_hash	str	PreparedAction.payload_hash	sha256:... hash
metadata	dict	ExecutionContext.input_params	additional context

---

4. SignResult

Signing result returned by the signer.

class SignResult(BaseModel):
    signature: str
    signature_format: str
    signer_ref: str

Field details

Field	Type	Description
signature	str	signing result: raw transaction bytes or a compact EVM signature depending on signature_format
signature_format	str	signing format identifier. Example: evm_raw_tx, eip712_compact, noop
signer_ref	str	Opaque signer-side reference ID; it must not embed key IDs, aliases, ARNs, credentials, or key material

signature_format values

The supported result formats are:

signature_format	Used for	Submit-side consumer
evm_raw_tx	Signed EVM raw transaction (legacy tx) broadcast	CCTP burn/mint, EVM erc20_transfer, USDT0/Stargate send, Gateway deposit/mint — RLP-decoded + recipient/target guarded
eip712_compact	Gateway burn-intent (EIP-712 typed-data) signature, plus Hyperliquid approve-agent typed-data signature	exec.gateway.intent — digest re-hashed and compared (EIP712_DIGEST_MISMATCH on mismatch)
eip191_compact	Strict SIWE message signature from AwsKmsEvmSigner	message job service — signature recovery must match the policy-pinned address
noop	No-op signer (CEX / dry-run lanes)	not broadcast

LocalPrivateKeySignerEvm deliberately rejects message intents. Browser-facing message signing is KMS-only through the private signer plane; there is no dev-key fallback.

Use in executors

In dispatch.py, QTG commits the movement signing job and attempt as SIGNING before calling the signer. It then commits the exact SignResult with SUCCEEDED before any checkpoint, pre-submit, or submit work. A same-digest recovery may reuse that result; a movement job never starts a second signer attempt. Temporary, cancellation, unexpected, and stale in-flight outcomes are ambiguous and escalate to manual intervention rather than returning the node to automatic signing.

The persisted sign_result is serialized to JSON and passed to executor.submit(). The CCTP burn/mint executors allow only signed raw transactions where signature_format == "evm_raw_tx"; the Gateway intent executor consumes the eip712_compact form.

---

5. NoopSigner

Implementation for tests and signer-free lane bindings.

class NoopSigner:
    def __init__(self, *, signer_key: str) -> None:
        self.signer_key = signer_key

When it is used

Scenario	Description
Test	dummy implementation to satisfy signer binding
CEX lane	on-chain signer is unnecessary because exchange API key auth is used
Dry-run	checks the full flow without signer infrastructure

---

6. AwsKmsEvmSigner

KMS implementation hosted by the private signer service and retained by explicit one-off tools.

Role

• Derives the signer EOA from an AWS KMS ECC_SECG_P256K1 key.
• Exposes signer_address from health().
• Validates the payload hash in sign() and signs EVM raw transactions, EIP-712 digests, or the independently derived EIP-191 digest for a strict SIWE message intent.
• Follows the current v1 architecture that reuses the same signer EOA across multiple EVM chains.

Required env

The private service uses MG_SIGNER_SIGNER_KEY, MG_SIGNER_KMS_KEY_ID, MG_SIGNER_AWS_REGION, optional profile/endpoint inputs, its nonce-HMAC credential, and a PostgreSQL nonce-store URL. Core receives only the matching MG_REMOTE_SIGNER_* settings and a pinned expected EVM address. See private-signer-service.md.

Explicit one-off tools continue to use MG_LOCAL_SIGNER_BACKEND=aws_kms_evm, MG_LOCAL_SIGNER_KMS_KEY_ID, MG_LOCAL_SIGNER_AWS_REGION, and the tool-specific reviewed acknowledgements. Those variables are rejected by qtg.main.

MG_LOCAL_SIGNER_KEY is a registry label, not a secret. The cryptographic key material never leaves AWS KMS — KMS_KEY_ID, AWS_REGION, and BACKEND are the load-bearing values.

Bootstrap rules

• qtg.main calls bootstrap_runtime(..., in_process_signers_allowed=False) and never constructs AwsKmsEvmSigner.
• The private signer service constructs exactly one AwsKmsEvmSigner and fails startup if KMS health or persistent nonce recording is unavailable.
• Explicit tools use the default signer-capable bootstrap mode and retain existing local KMS preflight rules.

health example

{
    "ok": True,
    "signer_address": "0x1234567890abcdef1234567890abcdef12345678",
    "chain_families": ["evm"],
    "backend": "aws_kms"
}

AwsKmsEvmSigner.health() does not return its registry label, KMS key ID, alias, or ARN. The logical registry signer_key remains available as the top-level registry field instead of being duplicated inside raw health. The registry projection additionally removes KMS identifier variants from custom or remote signer health before API responses or DB capability persistence. The configured KMS identifier remains internal to the signer for AWS API calls.

Operational references

• preflight: uv run python -m qtg.interfaces.tools.cctp_live_preflight
• retained TESTNET one-shot:

QTG_CCTP_LIVE_E2E=1 uv run python -m qtg.interfaces.tools.cctp_live_e2e \
  --template-key cctp.single_lane_usdc \
  --template-version <approved-version> \
  --checkpoint-path <new-local-packet-path> \
  --i-understand-this-can-sign-and-broadcast

The one-shot additionally requires an AWS KMS signer, the durable TESTNET database, and fresh human approval for the exact run. The command and this document do not grant live authority; pytest cannot arm CCTP signing or broadcast.

---

7. RemoteSignerProxy

Proxy implementation that delegates over HTTP to a remote signer service.

Current position

• It is the only signer implementation accepted by the long-running qtg.main process.
• Every /health and /sign request uses a fresh timestamp/nonce HMAC bound to method, path, raw query, and exact body bytes.
• Core pins the expected EVM address and verifies authenticated health immediately before signing.
• The private server commits each nonce to PostgreSQL before signer I/O; replay-store failure is fail-closed.

Constructor

class RemoteSignerProxy:
    def __init__(
        self,
        *,
        signer_key: str,
        base_url: str,
        hmac_key_id: str,
        hmac_secret: bytes,
        expected_signer_address: str,
        timeout: float = 30.0,
        client: httpx.AsyncClient | None = None,
    ) -> None:

Parameter	Description
signer_key	registry unique key
base_url	exact private signer service origin
hmac_key_id / hmac_secret	dedicated Core-to-signer nonce-HMAC credential
expected_signer_address	pinned nonzero EVM address checked against authenticated health
timeout	HTTP timeout
client	injected client for tests

Error mapping

The implementation does not raise raw httpx exceptions directly. It converts them into MovementError variants. JEP-735 then treats a movement signing-call failure conservatively; a transport or server error does not authorize an automatic second signing attempt.

---

7b. LocalPrivateKeySignerEvm

Development-only signer (MG_LOCAL_SIGNER_BACKEND=local_private_key_evm) that holds the EVM private key in process memory. Produces the same evm_raw_tx and eip712_compact signature formats and the same lowercase signer_address derivation as AwsKmsEvmSigner, so the proving lane and the signed-recipient guards behave identically.

• Key source backends: op (1Password CLI, recommended Tier-3) or plain (env var, dev only).
• Applies process hygiene at bootstrap (prctl(PR_SET_DUMPABLE=0) on Linux, setrlimit(RLIMIT_CORE, 0) on Linux + macOS) and fails closed if hygiene cannot be applied.
• Not for production fund movement. The AWS-KMS-only operator preflights do not cover it.

Full operator reference: local-private-key-signer.md.

---

8. Registry / caller verification

• GET /v3/signers exposes expected_signer_address, observed_signer_address, and the derived identity_state separately for EVM rows; non-EVM rows report identity as not applicable.
• PUT /v3/signers/{signer_key}/expected-identity is the sole enrollment writer for expected_signer_address; it uses a reasoned compare-and-set request and a fresh SignerIdentityProtocol observation.
• Health refresh is the sole writer for observed_signer_address. It clears that value when a signer becomes orphaned, so stale runtime evidence is never presented as current.
• PATCH /v3/signers/{signer_key} can switch the signer state between active and disabled.
• CCTP burn dispatch precheck and mint preflight cross-check the signer address against destination_caller; a mismatch fails closed as SIGNER_CALLER_MISMATCH.
• This contract does not add movement-time or rotation-time drift enforcement; that boundary is a separate follow-up.

---

9. Practical getting-started

1. For a Core runtime, configure the private signer service and matching MG_REMOTE_SIGNER_* values from private-signer-service.md. Do not put AWS/KMS settings in qtg.main.
2. For an explicitly approved one-off tool, configure its documented MG_LOCAL_SIGNER_* inputs and run its read-only preflight:

uv run python -m qtg.interfaces.tools.cctp_live_preflight

3. Run the retained TESTNET one-shot only after fresh human approval:

QTG_CCTP_LIVE_E2E=1 uv run python -m qtg.interfaces.tools.cctp_live_e2e \
  --template-key cctp.single_lane_usdc \
  --template-version <approved-version> \
  --checkpoint-path <new-local-packet-path> \
  --i-understand-this-can-sign-and-broadcast

The environment flag and explicit acknowledgement are both required software gates, but neither grants live authority. A fresh reviewed human approval is still required for the exact run.

At the current point, the project already has preflight / retained CLI / runbook + a successful staged testnet E2E record. JEP-738 extraction/authentication and the no-live JEP-734 strict-SIWE backend contract are implemented. Both features remain disabled by default: no production migration, signer deployment, KMS operation, Snap permission, public release, or W2 activation is authorized by this document. JEP-735 movement jobs still remain fixed to one attempt and do not inherit message retry semantics.