{"id":16177498,"url":"https://github.com/nevermined-io/contracts","last_synced_at":"2026-01-30T09:23:10.568Z","repository":{"id":37803271,"uuid":"256464155","full_name":"nevermined-io/contracts","owner":"nevermined-io","description":"📝 Smart Contracts implementation of Nevermined in Solidity","archived":false,"fork":false,"pushed_at":"2024-09-02T15:40:20.000Z","size":122835,"stargazers_count":13,"open_issues_count":19,"forks_count":2,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-04T12:54:11.711Z","etag":null,"topics":["contract","nevermined","smart","solidity"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@nevermined-io/contracts","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nevermined-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-17T09:48:07.000Z","updated_at":"2024-05-20T08:43:42.000Z","dependencies_parsed_at":"2023-07-17T20:21:56.569Z","dependency_job_id":"e8019c99-5375-4917-a6e4-830505267533","html_url":"https://github.com/nevermined-io/contracts","commit_stats":{"total_commits":1410,"total_committers":19,"mean_commits":74.21052631578948,"dds":0.6113475177304964,"last_synced_commit":"ac705ede55e1ff807f887eebc6f0b2fccfa613e7"},"previous_names":["keyko-io/nevermind-contracts","keyko-io/nevermined-contracts"],"tags_count":113,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevermined-io%2Fcontracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevermined-io%2Fcontracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevermined-io%2Fcontracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevermined-io%2Fcontracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nevermined-io","download_url":"https://codeload.github.com/nevermined-io/contracts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219869432,"owners_count":16555538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contract","nevermined","smart","solidity"],"created_at":"2024-10-10T05:09:13.282Z","updated_at":"2026-01-30T09:23:10.563Z","avatar_url":"https://github.com/nevermined-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![banner](https://raw.githubusercontent.com/nevermined-io/assets/main/images/logo/banner_logo.png)](https://nevermined.ai)\n\n# Nevermined Protocol\n\n\u003e 💧 AI Agents payment protocol implementation in Solidity\n\u003e [nevermined.ai](https://nevermined.ai)\n\n## Table of Contents\n\n- [Nevermined Protocol](#nevermined-protocol)\n  - [Table of Contents](#table-of-contents)\n  - [Overview](#overview)\n    - [Key Features](#key-features)\n  - [Architecture](#architecture)\n    - [Use Cases](#use-cases)\n    - [Core Components](#core-components)\n    - [Conditions System](#conditions-system)\n    - [Agreement Templates](#agreement-templates)\n    - [Contract Inheritance and Relationships](#contract-inheritance-and-relationships)\n    - [Access Control System](#access-control-system)\n  - [Setup and Installation](#setup-and-installation)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n  - [Development Scripts](#development-scripts)\n    - [Building and Compiling](#building-and-compiling)\n    - [Testing](#testing)\n    - [Local Development](#local-development)\n    - [Code Quality](#code-quality)\n    - [Deployment](#deployment)\n  - [Contract Interaction Flow](#contract-interaction-flow)\n  - [Contributors](#contributors)\n  - [License](#license)\n\n## Overview\n\nNevermined Smart Contracts form the core of the Nevermined protocol, enabling secure agents and payments plan registration (ERC-8004 compliant), access control, and payment management in a decentralized environment. This protocol facilitates the entire lifecycle of digital assets, from registration and pricing to access management and payment processing.\n\nThe Nevermined protocol allows users to:\n\n- Register AI agents and payment plans with flexible pricing models\n- Set up various subscription and one-time payment plans\n- Manage access rights through NFT-based credit systems\n- Process both cryptocurrency and fiat payments\n- Establish time-limited (expirable) and fixed-amount access rights\n- Execute agreements between parties with automated condition fulfillment\n- Distribute payments to multiple receivers with configurable fee structures\n\n### Key Features\n\n- **Asset Registration**: Register digital assets with customizable access plans\n- **Agreement Management**: Create and manage agreements between parties with condition-based fulfillment\n- **Payment Handling**: Secure escrow and distribution of payments\n- **Access Control**: NFT-based credits system for managing access rights\n- **Configurable Fees**: Network fee management for platform sustainability\n- **Upgradeable Contracts**: Future-proof design with UUPS pattern\n- **Multi-token Support**: Native cryptocurrency and ERC20 token support\n- **Role-based Access**: Granular permissions management\n\n## Architecture\n\nThe Nevermined Smart Contracts are organized around several core components:\n\n![Nevermined Architecture](docs/nevermined_architecture.png)\n\n### Use Cases\n\nThe protocol supports various use cases, including:\n\n* [Crypto Payment Flow](docs/flows/Crypto-Payment-Plan.md)\n* [Fiat Payment Flow](docs/flows/Fiat-Payment-Plan.md)\n* [Pay-as-you-go Payment Flow (Crypto)](docs/flows/Pay-as-you-go.md)\n* [Subscription Payment Flow (Fiat)](docs/flows/Subscription-Payment-Plan.md)\n* [AI Agent Requests and Redemption Flow](docs/flows/Requests-and-Redemption.md)\n\nYou can find more information in the [Nevermined Protocol Flows folder](docs/flows).\n\n### Core Components\n\n1. **NVMConfig**\n   - Central registry for roles, fees, and contract addresses\n   - Manages access control and permissions\n   - Stores configuration parameters\n   - Provides role-based access control for critical operations\n   - Supports upgradeable contracts through UUPS pattern\n\n2. **AssetsRegistry**\n   - Compliant with the ERC-8004 Identity Registry\n   - Manages asset registration and metadata\n   - Handles access plans and pricing configurations\n   - Supports different pricing models (fixed price, fiat price, smart contract price)\n   - Generates unique identifiers for assets and plans\n   - Validates and enforces fee structures\n\n3. **AgreementsStore**\n   - Stores and tracks agreements between parties\n   - Manages condition states and fulfillment\n   - Provides agreement verification\n   - Tracks dependencies between conditions\n   - Ensures proper sequencing of condition fulfillment\n\n4. **PaymentsVault**\n   - Escrow for holding and releasing payments\n   - Supports both native tokens and ERC20 tokens\n   - Manages deposit and withdrawal permissions\n   - Implements secure withdrawal patterns\n   - Provides balance tracking for different token types\n\n5. **NFT1155Credits**\n   - ERC1155-based NFT implementation for access rights\n   - Supports different credit types (expirable, fixed, dynamic)\n   - Manages minting and burning of access tokens\n   - Implements time-based expiration for credits\n   - Controls redemption based on configurable rules\n\n### Conditions System\n\nThe protocol uses a condition-based agreement system where specific conditions must be met before payments are released or access is granted:\n\n- **LockPaymentCondition**: Handles locking payments in escrow\n- **TransferCreditsCondition**: Manages the transfer of access credits\n- **DistributePaymentsCondition**: Controls payment distribution to receivers\n- **FiatSettlementCondition**: Manages off-chain fiat payment verification\n\n### Agreement Templates\n\n- **FixedPaymentTemplate**: Template for agreements with fixed payment terms\n- **FiatPaymentTemplate**: Template for agreements with fiat payment terms\n\n### Contract Inheritance and Relationships\n\nThe contracts follow a modular design with clear separation of concerns:\n\n- Core contracts manage configuration, assets, agreements, and payments\n- Template contracts orchestrate agreement creation and condition fulfillment\n- Condition contracts implement specific business logic for different agreement types\n- Token contracts handle the minting, burning, and tracking of access rights\n\n### Access Control System\n\nThe protocol implements a comprehensive role-based access control system:\n\n- **OWNER_ROLE**: Full administrative control\n- **GOVERNOR_ROLE**: Configuration management\n- **CREDITS_MINTER_ROLE**: Ability to mint access credits\n- **CREDITS_BURNER_ROLE**: Ability to burn access credits\n- **DEPOSITOR_ROLE**: Ability to deposit funds into the vault\n- **WITHDRAW_ROLE**: Ability to withdraw funds from the vault\n- **FIAT_SETTLEMENT_ROLE**: Ability to verify fiat payments\n\n## Setup and Installation\n\n### Prerequisites\n\n- Node.js (\u003e= 22.x)\n- Yarn (\u003e= 1.22.x)\n- Git\n- Foundry (for advanced testing and deployment)\n\n### Installation\n\n```bash\n# Install dependencies\nyarn install\n\n# Install Foundry (if not already installed)\ncurl -L https://foundry.paradigm.xyz | bash\nfoundryup\n```\n\n## Development Scripts\n\nThe project includes several scripts to help with development:\n\n### Building and Compiling\n\n```bash\n# Install dependencies\nyarn install\n\n# Compile contracts\nyarn compile\n```\n\n### Testing\n\n```bash\n# Run unit tests\nyarn test\n\n# Run integration tests\nyarn test:integration\n\n# Run tests with gas reporting\nyarn test:gas\n\n# Run test coverage\nyarn coverage\n```\n\n### Local Development\n\n```bash\n# Start a local Anvil chain (Foundry)\nanvil\n```\n\n### Code Quality\n\n```bash\n# Lint Solidity code\nyarn lint\n\n# Fix linting issues\nyarn lint:fix\n\n# Format code\nyarn format\n\n# Test coverage\nyarn coverage\n\n# Gas usage report\nyarn test:gas\n```\n\n### Deployment\n\n```bash\n# Deploy contracts (general)\nyarn deploy\n\n# Deploy to local network\nyarn deploy:local\n\n# Deploy to Sepolia testnet\nyarn deploy:sepolia\n```\n\n## Contract Interaction Flow\n\nA typical interaction flow in the Nevermined protocol:\n\n1. The asset owner registers an asset with pricing plans in the AssetsRegistry\n2. The consumer creates an agreement using a template (e.g., FixedPaymentTemplate)\n3. Payment is locked in the PaymentsVault (LockPaymentCondition)\n4. Access credits are transferred to the consumer (TransferCreditsCondition)\n5. Payments are distributed to receivers (DistributePaymentsCondition)\n\n\n## Contributors\n\nThis project exists thanks to all the people who contribute:\n\n\u003cimg src=\"https://github.com/aaitor.png\" width=\"60px;\"/\u003e \u003cb\u003eAitor Argomaniz\u003c/b\u003e - [@aaitor](https://github.com/aaitor) \u003cbr/\u003e\n\u003cimg src=\"https://github.com/ankurdubey521.png\" width=\"60px;\"/\u003e \u003cb\u003eAnkur Dubey\u003c/b\u003e - [@ankurdubey521](https://github.com/ankurdubey521) \u003cbr/\u003e\n\u003cimg src=\"https://github.com/eruizgar91.png\" width=\"60px;\"/\u003e \u003cb\u003eEnrique Ruiz\u003c/b\u003e - [@eruizgar91](https://github.com/eruizgar91) \u003cbr/\u003e\n\n## License\n\n```text\nCopyright 2025 Nevermined AG\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevermined-io%2Fcontracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnevermined-io%2Fcontracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevermined-io%2Fcontracts/lists"}