How skyfire-xyz/kyapay works
1. Repository purpose
- This repo is primarily a protocol specification and reference example repository for KYAPay, an identity-linked payment protocol based on JWT tokens.
- It is not a single application or service; the architecture is split between specification documents and example verification code.
2. Top-level structure
- The root contains mostly governance, licensing, and specification process documents: community license, scope, notices, license, governance, contributing, code of conduct, maintainer info.
- This makes the repo’s first boundary clear: spec/content governance vs code examples.
3. Specification and model layer
- docs/data-model.md defines the core JWT data model for KYAPay.
- docs/example-api.md defines the example API surface and expected protocol interactions.
- These docs are the canonical source for how tokens and API exchanges are structured.
4. Example implementation layer
- code-examples/verifyToken contains the executable references for token validation.
- The examples are duplicated in Python and TypeScript, showing the same protocol logic in two runtimes rather than serving different product features.
5. Protocol flow: token verification
- The main runtime use case is: receive a KYAPay JWT token → parse/configure protocol inputs → verify token semantics/signature/claims → determine whether the token is valid for a target party.
- The repo’s examples are centered on verifying tokens in two common contexts:
- verifyKyaTokenToExternalSeller
- verifyKyaPayTokenToOnboardedService
6. Two verification scenarios
- verifyKyaTokenToExternalSeller suggests validation for a token presented to an external seller.
- verifyKyaPayTokenToOnboardedService suggests validation for a token used with a pre-onboarded service.
- Architecturally, this implies the protocol supports at least two trust boundaries: external counterparties and registered/onboarded services.
7. Shared helper boundary
- Each language implementation has a helpers folder with:
- common utilities
- kya-specific logic
- pay-specific logic
- This indicates a clean split between shared token plumbing and token-type-specific verification rules.
8. Configuration and utility layer
- config and utils modules exist in both Python and TypeScript examples.
- These likely hold environment-specific values, constants, and helper routines needed to run the reference verification flow without embedding protocol details directly in the main scripts.
9. Language/runtime split
- The examples are implemented in Python and TypeScript/Node.js, each with its own dependency manifest (requirements.txt, package.json, tsconfig.json).
- This matters architecturally because the repo demonstrates the protocol as language-agnostic, while keeping each runtime’s implementation isolated.
10. External dependencies and integration points
- The practical integration boundary is the JWT ecosystem: whatever libraries are used, the core architecture expects token parsing and verification support from the runtime.
- No server, database, or deployment infrastructure is defined in the repo; the code examples appear to be offline/reference verification flows rather than a hosted application.
11. Documentation-driven architecture
- The repo’s intended architecture is document-first: the data model and example API define the contract, and the sample code demonstrates how clients enforce it.
- For diagramming, place the docs/specs as the authoritative source feeding the two reference implementations.
12. Overall mental model
- The system is best drawn as:
- Governance/licensing layer
- Protocol specification layer
- Reference token-verification implementations
- Two target trust contexts: external seller vs onboarded service
- There is no single backend; the repo is a protocol standard plus sample validators.
Main entry points: example-api.md Example API · verifyKyaTokenToExternalSeller.py External seller · verifyKyaPayTokenToOnboardedService.py Onboarded service · verifyKyaTokenToExternalSeller.ts External seller
Components 27
Governance
Repository policy, licensing, and maintenance documents
- Contributor license · Contributor agreement and licensing terms
.0_CS_Contributor_License_Agreement.md - Community license · Specification license for community use
1._Community_Specification_License-v1.md - Scope · Repository scope and boundaries
2._Scope.md - Notices · Legal notices and attribution
3._Notices.md - License · Primary project license
4._License.md - Governance · Governance and process rules
5._Governance.md - Contributing · Contribution workflow and expectations
6._Contributing.md - Code of conduct · Community conduct policy
8._Code_of_Conduct.md - Maintainers · Maintainer roles and contacts
MAINTAINERS.md
Specifications
Protocol model and example API definitions
- Data model · Core KYAPay JWT data model
docs/data-model.md - Example API · Example API surface and interaction model
docs/example-api.md
Python examples
Reference verification flow in Python
- Config · Python runtime configuration
code-examples/verifyToken/python/config.py - Utils · Shared Python utility routines
code-examples/verifyToken/python/utils.py - Common · Shared token plumbing and reusable helpers
code-examples/verifyToken/python/helpers/common.py - KYA helpers · KYA-specific verification logic
code-examples/verifyToken/python/helpers/kya.py - PAY helpers · PAY-specific verification logic
code-examples/verifyToken/python/helpers/pay.py - External seller · Verifies a KYA token for an external seller trust boundary
code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py - Onboarded service · Verifies a KYA Pay token for a pre-onboarded service
code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py
TypeScript examples
Reference verification flow in TypeScript
- Config · TypeScript runtime configuration
code-examples/verifyToken/typescript/src/config.ts - Utils · Shared TypeScript utility routines
code-examples/verifyToken/typescript/src/utils.ts - Common · Shared token plumbing and reusable helpers
code-examples/verifyToken/typescript/src/helpers/common.ts - KYA helpers · KYA-specific verification logic
code-examples/verifyToken/typescript/src/helpers/kya.ts - PAY helpers · PAY-specific verification logic
code-examples/verifyToken/typescript/src/helpers/pay.ts - External seller · Verifies a KYA token for an external seller trust boundary
code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts - Onboarded service · Verifies a KYA Pay token for a pre-onboarded service
code-examples/verifyToken/typescript/src/verifyKyaPayTokenToOnboardedService.ts
Other components
- KYAPay · Identity-linked payment protocol specification and reference examples
- JWT libs · Token parsing and verification support from the host runtime
Connections 37
- KYAPay → Contributor license: governed by · Repository governance and legal terms
- KYAPay → Community license: governed by · Repository governance and legal terms
- KYAPay → Scope: defines · Repository governance and legal terms
- KYAPay → Notices: defines · Repository governance and legal terms
- KYAPay → License: defines · Repository governance and legal terms
- KYAPay → Governance: defines · Repository governance and legal terms
- KYAPay → Contributing: defines · Repository governance and legal terms
- KYAPay → Code of conduct: defines · Repository governance and legal terms
- KYAPay → Maintainers: defines · Repository governance and legal terms
- KYAPay → Data model: specifies · Authoritative protocol model
- KYAPay → Example API: specifies · Authoritative protocol model
- Data model → Common: informs · Protocol model shapes validation helpers
- Data model → Common: informs · Protocol model shapes validation helpers
- Example API → External seller: drives · Example API is exercised by reference verifiers
- Example API → Onboarded service: drives · Example API is exercised by reference verifiers
- Example API → External seller: drives · Example API is exercised by reference verifiers
- Example API → Onboarded service: drives · Example API is exercised by reference verifiers
- JWT libs → External seller: supports · JWT parsing and verification library support
- JWT libs → Onboarded service: supports · JWT parsing and verification library support
- JWT libs → External seller: supports · JWT parsing and verification library support
- JWT libs → Onboarded service: supports · JWT parsing and verification library support
- Config → External seller: configures · Runtime settings for the verification flow
- Config → Onboarded service: configures · Runtime settings for the verification flow
- Utils → External seller: supports · Reusable runtime utilities
- Utils → Onboarded service: supports · Reusable runtime utilities
- Common → KYA helpers: shared by · Common helper layer used by token-specific logic
- Common → PAY helpers: shared by · Common helper layer used by token-specific logic
- KYA helpers → External seller: used by · KYA-specific validation path
- PAY helpers → Onboarded service: used by · PAY-specific validation path
- Config → External seller: configures · Runtime settings for the verification flow
- Config → Onboarded service: configures · Runtime settings for the verification flow
- Utils → External seller: supports · Reusable runtime utilities
- Utils → Onboarded service: supports · Reusable runtime utilities
- Common → KYA helpers: shared by · Common helper layer used by token-specific logic
- Common → PAY helpers: shared by · Common helper layer used by token-specific logic
- KYA helpers → External seller: used by · KYA-specific validation path
- PAY helpers → Onboarded service: used by · PAY-specific validation path