Contributing to SATI

May 13, 2026 · View on GitHub

Thank you for your interest in SATI! This is a community-driven standard.

How to Contribute

1. Specification Feedback

Review docs/specification.md and open issues for:

  • Technical concerns
  • Security considerations
  • Design improvements
  • Use case gaps

2. Integration Proposals

Building an agent framework or protocol? We'd love to hear about:

  • Integration requirements
  • Missing features
  • Compatibility concerns

3. Implementation Contributions

SATI Program:

  • Bug fixes and optimizations
  • Test coverage improvements
  • Security hardening

SDK:

  • Helper functions
  • Documentation
  • Additional examples

Schemas:

  • Schema improvements
  • Validation helpers

Development Setup

# Prerequisites
# - Rust 1.89.0 (locked via rust-toolchain.toml)
# - Solana CLI 2.0+
# - Anchor 0.32.1+
# - Node.js 18+
# - pnpm

# Setup
git clone https://github.com/cascade-protocol/sati.git
cd sati
pnpm install
anchor build
pnpm --filter @cascade-fyi/sati-sdk build
anchor test

Code Style

Rust (Anchor Programs)

// Follow Anchor best practices
// Use rustfmt for formatting
pub fn register_agent(
    ctx: Context<RegisterAgent>,
    name: String,
    symbol: String,
    uri: String,
) -> Result<()> {
    // Validate inputs
    require!(name.len() <= MAX_NAME_LENGTH, SatiRegistryError::NameTooLong);

    // Implementation...
    Ok(())
}

TypeScript (SDK)

// Use @solana/kit (NOT @solana/web3.js for new code)
// Generated code uses Codama - don't edit src/generated/
import { address, type Address } from "@solana/kit";
import { getRegisterAgentInstructionAsync } from "./generated";

// Helper functions go in src/helpers.ts
export function toAddress(pubkey: PublicKey): Address {
  return address(pubkey.toBase58());
}

SDK Structure

packages/sdk/
├── scripts/
│   └── generate-clients.ts  # Codama generation script
├── src/
│   ├── generated/           # Auto-generated (DO NOT EDIT)
│   ├── helpers.ts           # Utility functions
│   ├── schemas.ts           # SAS schema definitions
│   └── index.ts             # Exports
└── package.json

Important: Never edit files in src/generated/. To update:

  1. Modify the Anchor program
  2. Run anchor build
  3. Run pnpm --filter @cascade-fyi/sati-sdk generate

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

PR Guidelines

  • Clear description: Explain what and why
  • Reference issues: Link to relevant issues
  • Tests: Add tests for new functionality
  • Documentation: Update docs for API changes
  • Small commits: Keep commits focused and atomic

AI-Assisted Contributions

This repo accepts AI-assisted PRs. It does not accept drive-by PRs where the human submitter has not read the issue or run the code.

If you open a PR, you are the author. "An agent wrote it" is not a defense for any of the rules below.

Before opening a PR

  • Read the linked issue end-to-end, including any options the maintainer enumerated. If the issue recommends an approach, implement that one or argue against it in the PR description before implementing something else.
  • Run the full validation checklist in .claude/CLAUDE.md locally. PRs that have not been built and tested locally will be closed.
  • If a fix touches the on-chain program, it almost certainly touches the SDK in packages/sdk/ and/or the dashboard in apps/dashboard/. Ship the matching changes in the same PR.
  • Tests must actually exercise the code path being fixed. A test that fails on input validation before reaching the patched line is not a regression test.

PR description

  • State the root cause in one paragraph, citing file and line.
  • State which option from the issue you implemented and why.
  • List what you tested locally and what you did not. "Devnet success path not tested" is a fine answer; silence is not.

What gets closed without review

  • PRs against issues you have not commented on.
  • PRs that pick the option the issue explicitly argued against, with no counter-argument.
  • PRs whose tests pass on the buggy code as well as the fixed code.
  • PRs that change on-chain account structs without regenerating the SDK.
  • Force-pushes over a PR that is already in review.

What gets a fast merge

  • A short PR description that matches the diff.
  • A failing test that turns green with the fix and would not have turned green on the buggy code.
  • Matching SDK + dashboard changes when the program ABI moves.
  • Clean pnpm -w check and cargo clippy -p sati --all-targets.

Testing

# Run all Anchor tests
anchor test

# Run specific test file
anchor test --skip-deploy -- tests/sati-registry.test.ts

# Build and test SDK
cd packages/sdk && pnpm build && pnpm test

Documentation

  • Code comments: Explain why, not what
  • Function docs: Document all public APIs
  • Examples: Add usage examples in SDK documentation
  • Specification: Update spec for protocol changes

Community

  • Questions: Use GitHub Discussions
  • Bugs: Open an issue with reproduction steps
  • Features: Discuss in issue before implementing
  • Twitter: @opwizardx

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.