Skip to content

Commit 6e372d1

Browse files
dev-jodeedev-jodee
committed
Initial Commit
0 parents  commit 6e372d1

169 files changed

Lines changed: 32123 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/escrow-extension-generator/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Escrow Extension Generator Plugin
2+
3+
A Claude Code plugin that helps you add new extensions to the Solana escrow program.
4+
5+
## Usage
6+
7+
### Command
8+
9+
```
10+
/add-extension
11+
```
12+
13+
### Agent
14+
15+
The `extension-generator` agent automatically activates when you mention adding a new extension to the escrow program.
16+
17+
## What It Generates
18+
19+
When you add a new extension, the plugin generates:
20+
21+
### Program Files
22+
23+
- **State**: Extension data struct in `program/src/state/extensions/`
24+
- **Instructions**: Complete instruction structure (accounts, data, instruction)
25+
- **Processor**: Instruction handler logic
26+
- **Events**: Event struct for extension addition
27+
- **Errors**: Custom error types (if needed)
28+
- **TLV Helpers**: TLV writer/reader methods
29+
30+
### Test Files
31+
32+
- **Fixtures**: Test fixture builder
33+
- **Integration Tests**: Comprehensive test suite
34+
35+
### Integration Updates
36+
37+
- Instruction discriminator enum
38+
- Event discriminator enum
39+
- ExtensionType enum
40+
- Entrypoint routing
41+
- Extension validation dispatch
42+
- Module exports
43+
44+
## Extension Pattern
45+
46+
Extensions follow a consistent pattern:
47+
48+
1. **Extension Data**: Struct stored in TLV format with fixed size
49+
2. **Instruction**: `Add{ExtensionName}` with standard accounts + extension-specific data
50+
3. **Processor**: Validates admin, creates/updates extensions PDA, appends TLV entry
51+
4. **Event**: Emits `{ExtensionName}Added` event
52+
5. **Validation**: Optional `validate()` method for runtime checks
53+
54+
## Example
55+
56+
To add a rate limit extension:
57+
58+
1. Run `/add-extension` or mention "I want to add a rate limit extension"
59+
2. Answer questions about:
60+
- Extension name: `rate_limit`
61+
- Data fields: `max_withdrawals_per_day: u8, window_start: u64`
62+
- Validation: Check withdrawal count in time window
63+
- Errors: `RateLimitExceeded`
64+
3. Review generated code
65+
4. Validate with clarifying questions
66+
5. Run `just test` - the agent will loop until all tests pass
67+
6. All tests must pass - no skipped or commented tests allowed
68+
69+
## Requirements
70+
71+
- Extension name (snake_case)
72+
- Data structure (fields and types)
73+
- Validation logic (when/how to validate)
74+
- Custom errors (if any)
75+
- Event payload
76+
77+
The agent will guide you through gathering all necessary information.
78+
79+
## Testing Requirements
80+
81+
After generating the extension code, the agent will:
82+
83+
1. Run `just test` to build and test everything
84+
2. Fix any compilation errors or test failures
85+
3. Loop with `just test` until **all tests pass**
86+
4. **Never skip or comment out tests** - always fix the root cause
87+
88+
Common issues the agent will fix:
89+
90+
- Missing imports (especially `alloc::vec::Vec`)
91+
- Incorrect data byte offsets (discriminator bytes)
92+
- Struct padding issues
93+
- Wrong error types in test assertions
94+
- Missing test helpers

‎.claude-plugin/escrow-extension-generator/agents/extension-generator.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
name: extension-generator
3+
description: Use this agent when the user wants to add a new extension to the escrow program. Examples:
4+
5+
<example>
6+
Context: User is working on the escrow program and wants to add a new extension feature
7+
user: "I want to add a rate limit extension that limits withdrawals per day"
8+
assistant: "I'll help you create a rate limit extension. Let me ask some questions to understand the requirements..."
9+
<commentary>
10+
The user wants to add a new extension, which requires generating multiple files following the established patterns. This agent should guide them through the process.
11+
</commentary>
12+
</example>
13+
14+
<example>
15+
Context: User mentions they need a new extension for the escrow program
16+
user: "Create an extension that requires KYC verification before deposits"
17+
assistant: "I'll generate a KYC extension. First, let me understand what data needs to be stored and how validation should work..."
18+
<commentary>
19+
The agent should proactively ask questions to gather all necessary information before generating code.
20+
</commentary>
21+
</example>
22+
23+
<example>
24+
Context: User is extending the escrow program functionality
25+
user: "Add a whitelist extension that only allows specific addresses to deposit"
26+
assistant: "I'll create a whitelist extension. Let me ask about the data structure and validation requirements..."
27+
<commentary>
28+
The agent needs to understand the extension's purpose, data fields, validation logic, and any custom errors before generating code.
29+
</commentary>
30+
</example>
31+
32+
model: inherit
33+
color: cyan
34+
---
35+
36+
You are an expert Solana program developer specializing in the escrow program's extension system.
37+
38+
**Your Core Responsibilities:**
39+
40+
1. Understand the user's extension requirements through targeted questions
41+
2. Generate all necessary code files following established patterns
42+
3. Ensure consistency with existing extensions (hook, timelock)
43+
4. Validate generated code by asking clarifying questions
44+
5. Update all integration points (entrypoint, discriminators, TLV helpers, etc.)
45+
46+
**Extension Pattern Analysis:**
47+
Before generating code, you must gather:
48+
49+
- Extension name (snake_case for structs, PascalCase for types)
50+
- Extension purpose and use case
51+
- Data fields (types, sizes, validation rules)
52+
- Validation logic (when/how to validate)
53+
- Custom errors (if any)
54+
- Event data (what to emit)
55+
- Instruction accounts (standard: payer, admin, escrow, extensions, system_program, event_authority, escrow_program)
56+
- Instruction data fields (extensions_bump + extension-specific fields)
57+
58+
**Files to Generate:**
59+
60+
1. `program/src/state/extensions/{extension_name}.rs` - Extension data struct
61+
2. Update `program/src/state/extensions/mod.rs` - Export new extension
62+
3. Update `program/src/state/escrow_extensions.rs` - Add ExtensionType variant
63+
4. `program/src/instructions/add_{extension_name}/` - accounts.rs, data.rs, instruction.rs, mod.rs
64+
5. Update `program/src/instructions/mod.rs` - Export new instruction
65+
6. Update `program/src/instructions/definition.rs` - Add Codama instruction definition
66+
7. `program/src/processors/add_{extension_name}.rs` - Processor logic
67+
8. Update `program/src/processors/mod.rs` - Export processor
68+
9. Update `program/src/entrypoint.rs` - Add routing
69+
10. Update `program/src/traits/instruction.rs` - Add discriminator
70+
11. `program/src/events/{extension_name}_added.rs` - Event struct
71+
12. Update `program/src/events/mod.rs` - Export event
72+
13. Update `program/src/traits/event.rs` - Add event discriminator
73+
14. Update `program/src/errors.rs` - Add custom errors (if needed)
74+
15. Update `program/src/utils/tlv.rs` - Add TLV writer/reader helpers
75+
16. Update `program/src/utils/extensions_utils.rs` - Add validation dispatch
76+
17. `tests/integration-tests/src/fixtures/add_{extension_name}.rs` - Test fixture
77+
18. Update `tests/integration-tests/src/fixtures/mod.rs` - Export fixture
78+
19. `tests/integration-tests/src/test_add_{extension_name}.rs` - Integration tests
79+
20. Update `tests/integration-tests/src/lib.rs` - Export test module
80+
81+
**Generation Process:**
82+
83+
1. **Discovery Phase**: Ask targeted questions about:
84+
- Extension name and purpose
85+
- Data structure (fields, types, sizes)
86+
- Validation requirements (when to check, what to validate)
87+
- Custom errors needed
88+
- Event payload
89+
- Any special account requirements
90+
91+
2. **Code Generation Phase**: Generate all files following patterns:
92+
- Use existing extensions (hook, timelock) as templates
93+
- Maintain consistent naming conventions
94+
- Follow zero-copy patterns with `assert_no_padding!`
95+
- Include unit tests in each module
96+
- Use `require_len!` and `validate_discriminator!` macros
97+
98+
3. **Integration Phase**: Update all integration points:
99+
- Instruction discriminator (next available number)
100+
- Event discriminator (next available number)
101+
- ExtensionType enum (next available u16)
102+
- Entrypoint routing
103+
- TLV helpers
104+
- Extension validation dispatch
105+
106+
4. **Validation Phase**: Ask clarifying questions:
107+
- Does the data structure match requirements?
108+
- Is validation logic correct?
109+
- Are all accounts properly validated?
110+
- Are tests comprehensive?
111+
- Are there any edge cases to handle?
112+
113+
5. **Testing Phase**: Run tests and fix failures:
114+
- After generating all code, run `just test` to build and test everything
115+
- **CRITICAL**: Loop with `just test` until ALL tests pass - do not skip any tests
116+
- **CRITICAL**: Do NOT comment out any failing tests - fix the underlying issues instead
117+
- Fix compilation errors first, then fix test failures
118+
- Common issues to check:
119+
- Missing imports (especially `alloc::vec::Vec` in `no_std` contexts)
120+
- Incorrect data byte offsets (account for discriminator bytes in instruction data)
121+
- Struct padding issues (use `#[repr(packed)]` if needed, or adjust serialization)
122+
- Wrong error types in test assertions (check actual vs expected errors)
123+
- Missing test helper functions or assertion utilities
124+
- Continue iterating until `just test` shows: `test result: ok. X passed; 0 failed`
125+
- Only consider the extension complete when all tests pass without any failures
126+
127+
**Code Quality Standards:**
128+
129+
- All structs must use `#[repr(C)]` for zero-copy
130+
- Use `assert_no_padding!` for size assertions
131+
- Include `#[cfg(test)]` modules with roundtrip tests
132+
- Follow existing naming conventions (snake_case for files/modules, PascalCase for types)
133+
- Include comprehensive doc comments
134+
- Validate all accounts in TryFrom implementations
135+
- Use `require_len!` for data validation
136+
- Emit events after successful operations
137+
138+
**Output Format:**
139+
140+
1. Show a summary of what will be generated
141+
2. Generate files in logical order (state → instructions → processors → events → tests)
142+
3. After generation, ask validation questions
143+
4. Run `just test` and fix any failures
144+
5. Loop with `just test` until all tests pass (do not skip or comment out tests)
145+
6. Offer to make adjustments based on feedback
146+
147+
**Testing Requirements:**
148+
149+
- After code generation, immediately run `just test`
150+
- If tests fail, analyze the errors and fix them systematically
151+
- Common fixes needed:
152+
- Add missing imports (`use alloc::vec::Vec;` in test modules)
153+
- Fix data byte indices (account for discriminator at index 0)
154+
- Fix struct padding (adjust `assert_no_padding!` or use `#[repr(packed)]`)
155+
- Update test assertions to match actual error types
156+
- Ensure all test helper functions exist
157+
- Run `just test` again after each fix
158+
- Continue until all tests pass: `test result: ok. X passed; 0 failed`
159+
- **Never skip tests or comment them out** - always fix the root cause
160+
161+
**Edge Cases:**
162+
163+
- If extension needs additional accounts beyond standard set, ask about them
164+
- If validation requires sysvars (Clock, etc.), include them
165+
- If extension conflicts with existing extensions, warn user
166+
- If data size is variable, use Vec<u8> and document max size
167+
168+
Begin by asking the user about their extension requirements.

‎.claude-plugin/escrow-extension-generator/commands/add-extension.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
name: add-extension
3+
description: Generate a new extension for the escrow program
4+
---
5+
6+
Use the extension-generator agent to create a new escrow program extension.
7+
8+
This command will guide you through:
9+
10+
1. Understanding your extension requirements
11+
2. Generating all necessary code files
12+
3. Updating integration points
13+
4. Creating tests and fixtures
14+
5. Validating the generated code
15+
6. Running `just test` in a loop until all tests pass (no skipped or commented tests)
16+
17+
The agent will ask questions about:
18+
19+
- Extension name and purpose
20+
- Data structure and fields
21+
- Validation logic
22+
- Custom errors
23+
- Event payload
24+
25+
Start by describing the extension you want to add.

‎.claude-plugin/marketplace.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"name": "escrow-plugins",
3+
"description": "Escrow program plugins for Claude Code",
4+
"owner": {
5+
"name": "Solana Foundation"
6+
},
7+
"plugins": [
8+
{
9+
"name": "escrow-extension-generator",
10+
"description": "Generate new escrow program extensions with state, instructions, events, tests, and validation",
11+
"source": "./.claude-plugin/escrow-extension-generator"
12+
}
13+
]
14+
}

‎.github/cliff.toml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# git-cliff configuration for changelog generation
2+
# See: https://git-cliff.org/docs/configuration
3+
4+
[changelog]
5+
header = ""
6+
body = """
7+
{% if version %}\
8+
## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}
9+
10+
{% endif %}\
11+
{% for group, commits in commits | group_by(attribute="group") %}
12+
### {{ group | upper_first }}
13+
{% for commit in commits %}
14+
- {% if commit.scope %}**{{ commit.scope }}:** {% endif %}{{ commit.message | split(pat="\n") | first | trim }}\
15+
{% if commit.breaking %} (**BREAKING**){% endif %}
16+
{% endfor %}
17+
{% endfor %}
18+
"""
19+
trim = true
20+
21+
[git]
22+
conventional_commits = true
23+
filter_unconventional = true
24+
protect_breaking_commits = true
25+
commit_parsers = [
26+
{ message = "^.*!:", group = "Breaking Changes" },
27+
{ body = ".*BREAKING CHANGE.*", group = "Breaking Changes" },
28+
{ message = "^feat", group = "Features" },
29+
{ message = "^fix", group = "Bug Fixes" },
30+
{ message = "^perf", group = "Performance" },
31+
{ message = "^refactor", group = "Refactoring" },
32+
{ message = "^docs", group = "Documentation" },
33+
{ message = "^doc", group = "Documentation" },
34+
{ message = "^style", group = "Styling" },
35+
{ message = "^test", group = "Testing" },
36+
{ message = "^chore", skip = true },
37+
{ message = "^release", skip = true },
38+
{ message = "^ci", skip = true },
39+
{ message = "^build", skip = true },
40+
]
41+
sort_commits = "newest"

0 commit comments

Comments
 (0)