Thank you for your interest in contributing to the Location Proofs ecosystem!
- 🐛 Report bugs - Open issues for bugs or unexpected behavior
- 💡 Propose features - Suggest new plugin types or improvements
- 📝 Improve documentation - Fix typos, add examples, clarify concepts
- 🔌 Build plugins - Implement new proof-of-location systems
- 🧪 Write tests - Improve test coverage and verification quality
- Node.js ≥ 18
- pnpm (recommended) or npm
- Familiarity with TypeScript
- Understanding of location proof systems
-
Fork the template (coming soon) or study existing plugins:
plugin-proofmode- Device-based proofsplugin-witnesschain- Infrastructure proofs
-
Implement the interface:
import type { LocationProofPlugin } from '@decentralized-geo/astral-sdk/plugins'; export class MyPlugin implements LocationProofPlugin { readonly name = 'my-plugin'; readonly version = '0.1.0'; readonly runtimes = ['node', 'browser']; async create(signals: RawSignals): Promise<UnsignedLocationStamp> { // Transform your proof system's signals into a LocationStamp } async verify(stamp: LocationStamp): Promise<StampVerificationResult> { // Validate signatures, structure, signal consistency } }
-
Write tests:
- Unit tests for all public methods
- Integration tests with real proof data
- Test fixtures for common scenarios
-
Document:
- README with installation, usage, API reference
- JSDoc comments on all public methods
- Examples for common use cases
-
Submit:
- Open an issue to discuss the plugin
- Create a PR with your implementation
- Respond to review feedback
Do:
- ✅ Follow the
LocationProofPlugininterface exactly - ✅ Return detailed verification results (not just boolean)
- ✅ Handle errors gracefully with descriptive messages
- ✅ Include type definitions for all public APIs
- ✅ Test with real proof data from your system
- ✅ Document trust assumptions and limitations
Don't:
- ❌ Implement evaluation logic (SDK handles this)
- ❌ Add blockchain dependencies (keep plugins chain-agnostic)
- ❌ Include large dependencies unnecessarily
- ❌ Make breaking changes without major version bump
Plugins implement verify() for internal validation:
- Check cryptographic signatures
- Validate signal structure and ranges
- Verify proof system-specific invariants
- Return detailed verification results
SDK handles evaluate() for credibility scoring:
- Spatial distance measurements
- Temporal overlap calculations
- Multidimensional credibility vectors
- Cross-stamp correlation
This separation keeps plugins focused on proof-system-specific logic while the SDK provides generalized evaluation.
- TypeScript: Strict mode, no
anytypes - Formatting: Prettier with default settings
- Linting: ESLint with recommended rules
- Naming: camelCase for variables/functions, PascalCase for classes/types
- Commits: Conventional commits format (
feat:,fix:,docs:, etc.)
Follow Conventional Commits:
<type>(<scope>): <subject>
<body>
<footer>
Types:
feat:- New featurefix:- Bug fixdocs:- Documentation onlyrefactor:- Code refactoringtest:- Add/update testschore:- Maintenance tasks
Example:
feat(verify): add SafetyNet attestation validation
Verify SafetyNet JWT signature and check device integrity
claims. Adds bonus credibility for passing attestation.
Refs: #42
Run tests before submitting:
pnpm test # Run all tests
pnpm test:watch # Watch mode
pnpm typecheck # Type checking
pnpm lint # LintingTest coverage expectations:
- All public methods must have tests
- Edge cases and error paths must be covered
- Integration tests with real proof data preferred
-
Fork the repository
-
Create a feature branch (
git checkout -b feat/my-feature) -
Commit your changes with conventional commits
-
Push to your fork
-
Open a pull request with:
- Clear description of changes
- Link to related issues
- Test results/screenshots if applicable
-
Respond to review feedback
-
Merge after approval (maintainers will merge)
All submissions require review. We look for:
- ✅ Correct implementation of plugin interface
- ✅ Comprehensive tests
- ✅ Clear documentation
- ✅ No breaking changes (or properly versioned)
- ✅ Clean, readable code
By contributing, you agree that your contributions will be licensed under the MIT License.
- Open an issue for technical questions
- Join our Discord (coming soon) for real-time discussion
- Email: developers@astral.global
Thank you for helping build the future of verifiable location! 🌍