Security
Key Custody and Protection
Pre-launch
Section
Security
Documentation category
Type
Guide
Technical reference
Summary
How the SWSS Technology Team holds and protects the signing material behind Foundation operations, and why the operational detail is deliberately unpublished.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Every settlement on SwssChain is authorised by a signature, and the material that produces that signature is the most concentrated point of risk in the entire ecosystem. The SWSS Technology Team treats custody of that material as a first-class engineering discipline operated directly by the Foundation, not as a configuration delegated to a supplier.

This page states what is true of that custody. It does not state how it is achieved, and the omission is deliberate: see the closing section.

Properties That Hold Across Foundation Signing Material

PropertyWhat it means in practice
Non-extractable by constructionSigning material used in Foundation operations is generated inside a hardware boundary and does not leave it. There is no export path, so there is no file to copy, no backup to steal and no environment variable to read
Signing occurs inside the boundaryA request to sign enters the boundary and a signature leaves it. Key material is never present in application memory, in a process environment, in a log or in a response
Custody separated from operationThe team that operates a service is not the team that holds the material that service signs with. Neither can complete a privileged action alone
Authorisation is multi-partyOperations of consequence require independent approvals from separate holders. No individual, including any individual engineer, can move a privileged operation from request to execution by themselves
Foundation-operated, not delegatedThe custody infrastructure is run by the SWSS Technology Team on infrastructure the Foundation controls. Custody is not outsourced to a third-party service whose own security posture would become SwssChain's
Access is attributableEvery authorised interaction with signing material is attributable to a named, verified person. There are no shared credentials and no unattributed access

The Member's Keys Are Not the Foundation's

A distinction that matters, and that is frequently confused when describing custodial infrastructure. The SWSS Identity Verification Layer authenticates a member and signs what that member has approved. It holds no balance, stakes nothing and moves nothing on its own initiative. Authority over what a member's holdings do belongs to the member, exercised through SWSS App.

The consequence is structural rather than procedural: a compromise of Foundation infrastructure does not become authority over member holdings, because that authority was never held there to be taken. This is the same principle the ecosystem applies at every boundary, set out in SWSS Ecosystem Security.

Continuity

Custody has to survive the loss of a device, a site or a person. Recovery material for Foundation signing operations is held under split control, geographically separated, and is itself subject to the multi-party rule: no single holder of recovery material can reconstruct a signing capability alone. Recovery procedures are exercised on a scheduled basis rather than assumed to work.

What Is Deliberately Not Published, and Why

The absence of detail here is a control, not an omission

SwssChain does not publish the makes and models of its custody hardware, its certification levels, its rotation intervals, its approval thresholds or the topology of its signing infrastructure. Each of those is a planning input for an attacker and none of them is verifiable by a reader in any case. An institution assessing SwssChain should expect these details under a due diligence engagement with the SWSS Foundation, where they can be evidenced and where the disclosure is scoped, not from a documentation page that is served to everyone equally.

Verifying an Authorisation Without Any Key Material

The property this page asserts is that key material is never present outside its boundary. That is visible in what a verification actually requires: a certificate is retrieved from the consensus layer and checked, and no private key exists anywhere in the exchange, not at the signing end, and not at the verifying end.

const res = await fetch(process.env.SWSS_RPC_ENDPOINT!, {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body:    JSON.stringify({
    jsonrpc: '2.0', method: 'swss_getFinalityCert', params: [txHash], id: 1,
  }),
})

const { result: cert } = await res.json()

// Assert, do not report. A settlement that cannot be shown to have been
// attested by the validator set must not be treated as settled.
if (!cert || cert.txHash !== txHash) {
  throw new Error(`no finality certificate for ${txHash}`)
}
if (cert.chainId !== EXPECTED_CHAIN_ID) {
  throw new Error(`certificate is from chain ${cert.chainId}, expected ${EXPECTED_CHAIN_ID}`)
}
if (!Array.isArray(cert.signatures) || cert.signatures.length === 0) {
  throw new Error(`certificate for ${txHash} carries no validator signatures`)
}

The chain identifier is checked explicitly because a certificate that is valid on one network is not evidence on another, and a certificate retrieved from the wrong endpoint would otherwise verify cleanly. Full verification, including signature checking, is documented in Finality Certificate Programmatic Verification.

Independent verification of these controls is addressed in Independent Assurance. The channel for reporting a weakness in any of them is set out in Reporting Vulnerabilities.