Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
56 changes: 56 additions & 0 deletions .github/workflows/publish_npm_scoped_x402_avm.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
name: Publish @x402/avm package to NPM

on:
workflow_dispatch:

jobs:
publish-npm-x402-avm:
runs-on: ubuntu-latest
environment: ${{ github.ref == 'refs/heads/main' && 'npm' || '' }}
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
pnpm install --frozen-lockfile
pnpm -r --filter=@x402/core --filter=@x402/extensions --filter=@x402/avm run build

- name: Publish @x402/avm package
working-directory: ./typescript/packages/mechanisms/avm
run: |
# Get package information directly
PACKAGE_NAME=$(node -p "require('./package.json').name")
PACKAGE_VERSION=$(node -p "require('./package.json').version")

echo "Package: $PACKAGE_NAME@$PACKAGE_VERSION"

# Check if running on main branch
if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
echo "Publishing to NPM (main branch)"
pnpm publish --provenance --access public
else
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
12 changes: 8 additions & 4 deletions .github/workflows/publish_npm_x402.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,23 @@ jobs:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -48,5 +54,3 @@ jobs:
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
14 changes: 9 additions & 5 deletions .github/workflows/publish_npm_x402_axios.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,23 @@ jobs:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -47,6 +53,4 @@ jobs:
else
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
fi
14 changes: 9 additions & 5 deletions .github/workflows/publish_npm_x402_express.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,23 @@ jobs:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -47,6 +53,4 @@ jobs:
else
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
fi
14 changes: 9 additions & 5 deletions .github/workflows/publish_npm_x402_fetch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,23 @@ jobs:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -47,6 +53,4 @@ jobs:
else
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
fi
22 changes: 16 additions & 6 deletions .github/workflows/publish_npm_x402_hono.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,25 @@ jobs:
id-token: write
steps:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
- uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
with:
version: 10.7.0
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -42,5 +54,3 @@ jobs:
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
22 changes: 16 additions & 6 deletions .github/workflows/publish_npm_x402_next.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,25 @@ jobs:
id-token: write
steps:
- uses: actions/checkout@v4

- name: Setup pnpm
uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061
with:
version: 10.7.0

- uses: actions/setup-node@v4
with:
node-version: "20"
node-version: "24"
registry-url: "https://registry.npmjs.org"
- uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda
with:
version: 10.7.0
cache: "pnpm"
cache-dependency-path: ./typescript

- name: Update npm for OIDC trusted publishing
run: npm install -g npm@latest

- name: Configure npm for trusted publishing
run: npm config delete always-auth 2>/dev/null || true

- name: Install and build
working-directory: ./typescript
run: |
Expand All @@ -42,5 +54,3 @@ jobs:
echo "Dry run only (non-main branch: ${{ github.ref }})"
pnpm publish --dry-run --no-git-checks
fi
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
2 changes: 1 addition & 1 deletion .github/workflows/publish_pypi_x402.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ jobs:
url: https://pypi.org/p/x402
permissions:
contents: read
id-token: write

steps:
- uses: actions/checkout@v4
Expand Down Expand Up @@ -45,4 +46,3 @@ jobs:
uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc
with:
packages-dir: python/x402/dist/
password: ${{ secrets.PYPI_X402_TOKEN }}
71 changes: 64 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,74 @@ x402 welcomes contributions of schemes, middleware, new chain support, and more.

## Contents

- [AI-Assisted Contributions](#ai-assisted-contributions)
- [Repository Structure](#repository-structure)
- [Language-Specific Guides](#language-specific-guides)
- [Contributing Workflow](#contributing-workflow)
- [Changelog Tooling](#changelog-tooling)
- [Commit Signing](#commit-signing)
- [Getting Help](#getting-help)

## AI-Assisted Contributions

Using AI tools (LLMs, code assistants, etc.) for contributions is acceptable, given the following:

- **You must review AI output before requesting review.** Do not open a non-Draft PR until you have personally verified the generated code. AI-generated PRs submitted without human review waste maintainer time and erode trust.
- **Remove verbosity and filler.** AI tools tend to produce verbose documentation, comments, PR descriptions, and commit messages. Strip these down to what is concise, clear, and useful — nothing more.
- **Remove redundant code and tests.** Deduplicate generated code, tests, and explanations. Explicitness and clarity are good; repetition and over-explanation are not.
- **Verify correctness, especially around payment and signature logic.** x402 handles real value transfer. AI tools hallucinate plausible-looking code that may be subtly wrong — incorrect signing flows, wrong chain constants, hallucinated headers that don't match the spec. You are responsible for catching these before submission.
- **Do not batch-generate low-effort PRs.** Submitting multiple narrow, machine-generated PRs in rapid succession is obvious and unhelpful. If AI helps you work faster, use that speed to produce fewer, higher-quality contributions — not more low-quality ones.
- **Disclose significant AI usage.** If the majority of a PR was generated by an AI tool, note this in the PR description. This is not a mark against the PR — it helps reviewers calibrate their review (e.g., checking for hallucinated APIs or fabricated test assertions).

Contributions that show clear signs of unreviewed AI output (generic filler comments, hallucination, redundant boilerplate, cookie-cutter PR descriptions) may be closed without detailed review.

### Sample Prompt for AI-Assisted Development

If you use an AI coding agent (Claude Code, Codex, Cursor, etc.) to work on x402, include the following in your agent's system prompt or project instructions. This ensures the agent's output aligns with x402 contribution standards before you review it.

```text
You are contributing to x402, an open protocol for internet-native payments.
x402 handles real value transfer — correctness is critical.

Follow these rules for all code, documentation, and commit messages you produce:

1. CONCISE OUTPUT ONLY. Do not add filler comments, redundant docstrings, or
verbose explanations. Every line of documentation or commentary must carry
useful information.

2. NO REDUNDANCY. Do not generate duplicate or near-duplicate code, tests, or
explanations. If logic already exists, use it — do not rewrite it. Three
similar lines are better than an unnecessary abstraction, but three identical
blocks are never acceptable.

3. VERIFY AGAINST THE SPEC. Before writing payment, signing, or settlement
logic, read the relevant spec in specs/. Do not invent header names, payload
fields, or signing flows. If you are unsure whether a field or constant
exists, search the codebase — do not guess.

4. MATCH EXISTING PATTERNS. Read the surrounding code before generating new
code. Match the style, naming conventions, error handling, and test patterns
already in use for that SDK (TypeScript, Python, Go, or Java).

5. DO NOT ADD UNREQUESTED FEATURES. Implement exactly what was asked. Do not
add extra configuration options, feature flags, helper utilities, or
"improvements" beyond the scope of the task.

6. COMMIT MESSAGES. Use conventional commits (feat:, fix:, docs:, chore:).
Keep the subject line under 72 characters. The body should explain why, not
what — the diff shows what changed.

7. CHAIN AND TOKEN CONSTANTS. Never hardcode chain IDs, token addresses, or
decimal values from memory. Always reference the constants defined in the
codebase (e.g., mechanisms/evm/constants, mechanisms/svm/constants).

8. TEST CORRECTNESS. Generated tests must assert meaningful behavior, not just
that "the function doesn't throw." Do not fabricate expected values — derive
them from the spec or existing test fixtures.
```

You can place this in a `CLAUDE.md`, `.cursorrules`, `codex-instructions.md`, or equivalent file at the root of your working copy. It is not committed to the repository — it is for your local development workflow.

## Repository Structure

The x402 repository contains implementations in multiple languages plus protocol specifications.
Expand Down Expand Up @@ -138,12 +199,8 @@ Because different chains have different best practices, a scheme may have a diff
### Adding a Default Asset for an EVM Chain

If your chain is EVM-compatible and you want to add a default stablecoin for
dollar-string pricing (`"$0.10"`), you don't need the full 3-PR workflow below. See:

- [Go: DEFAULT_ASSET.md](go/mechanisms/evm/DEFAULT_ASSET.md)
- [TypeScript: DEFAULT_ASSET.md](typescript/packages/mechanisms/evm/src/exact/server/DEFAULT_ASSET.md)

These guides include a cross-SDK checklist of every file to update.
dollar-string pricing (`"$0.10"`), you don't need the full 3-PR workflow below. See
[DEFAULT_ASSETS.md](DEFAULT_ASSETS.md) for instructions.

### Adding a New Chain Family

Expand All @@ -168,7 +225,7 @@ After spec approval, implement in a **single SDK** (TypeScript, Python OR Go).
| SDK | Interfaces |
|-----|------------|
| TypeScript (`@x402/core`) | `SchemeNetworkClient`, `SchemeNetworkServer`, `SchemeNetworkFacilitator` |
| Go (`github.com/coinbase/x402/go`) | `ClientScheme`, `ServerScheme`, `FacilitatorScheme` |
| Go (`github.com/x402-foundation/x402/go`) | `ClientScheme`, `ServerScheme`, `FacilitatorScheme` |
| Python (`x402`) | `SchemeNetworkClient`, `SchemeNetworkServer`, `SchemeNetworkFacilitator` |

**Required tests:**
Expand Down
Loading
Loading