The Filecoin Pay V1 contract enables ERC20 token payment flows through "rails" - automated payment channels between payers and recipients. The contract supports continuous rate based payments, one-time transfers, and payment validation during settlement.
| If you want to... | Read |
|---|---|
| Understand the model: accounts, rails, lockup, validators, operators | Concepts |
| Build a service contract or integrate as an operator: function reference, worked example, escape hatches | Integration Guide |
| Monitor solvency and rail health from a dashboard or SDK: paid-until, runway, termination windows | Monitoring |
| Dig into contract internals: settlement, rate-change segments, invariants, fees | SPEC.md |
| Find deployed contract addresses | CHANGELOG.md |
Notable sections:
- Per-Rail Lockup: the safety-hatch model: why locked funds are a guarantee, not a pre-payment
- Worked Example: a full deal lifecycle from deposit to withdrawal
- Emergency Scenarios: escape hatches when an operator, validator, or counterparty misbehaves
- Known Issues: current v1 quirks such as the operator lockup-usage leak (#274)
- Account: Represents a user's token balance and locked funds
- Rail: A payment channel between a payer and recipient with configurable terms
- Validator: An optional contract that acts as a trusted "arbitrator". It can:
- Validate and modify payment amounts during settlement.
- Veto a rail termination attempt from any party by reverting the
railTerminatedcallback. - Decide the final financial outcome (the total payout) of a rail that has been successfully terminated.
- Operator: An authorized third party who can manage rails on behalf of payers
See Concepts for the full model.
Check the latest deployed contracts in CHANGELOG.md
The Filecoin-Pay contracts have undergone the following security audits:
We welcome contributions to the payments contract! To ensure consistency and quality across the project, please follow these guidelines when contributing.
- New Features: Always create an issue first and discuss with maintainers before implementing new features. This ensures alignment with project goals and prevents duplicate work.
- Bug Fixes: While you can submit bug fix PRs without prior issues, please include detailed reproduction steps in your PR description.
- Link to Issue: All feature PRs should reference a related issue (e.g., "Closes #123" or "Addresses #456").
- Clear Description: Provide a detailed description of what your PR does, why it's needed, and how to test it.
- Tests: Include comprehensive tests for new functionality or bug fixes.
- Documentation: Update relevant documentation for any API or behavior changes.
This project follows the Conventional Commits specification. All commit messages should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)refactor: A code change that neither fixes a bug nor adds a featuretest: Adding missing tests or correcting existing testschore: Changes to the build process or auxiliary tools and libraries
Examples:
feat: add rail termination functionalityfix: resolve settlement calculation bugdocs: update README with new API exampleschore: update dependencies
Following these conventions helps maintain a clear project history and makes handling of releases and changelogs easier.
Dual-licensed under MIT + Apache 2.0