Developer quick start

This path takes you from read → install → copy template → modify → test → submit. It uses the local Hardhat chain and does not require a wallet, testnet funds, or external RPC access.

1. Read

Start with the adapter system, adapter trust model, and security model. Then review the reference adapters and adapter registry.

Asset, oracle, compliance, and liquidation adapters are shared multi-tenant instances. Position adapters are EIP-1167 clones. Runtime calls must resolve configuration from the configured market and fail closed when dependencies are invalid or unavailable.

2. Install

git clone https://github.com/roadsidedev/OpenAsset.git
cd OpenAsset/contracts
npm install
npm run compile
cd ../sdk
npm install
npm test

Once published, install the SDK with npm install @openasset/adapter-sdk. For a repository-local adapter project, use npm install file:../OpenAsset/sdk.

3. Copy a template

Generate an interface-safe scaffold:

npx create-openasset-adapter --type oracle --name MyOracleAdapter

Supported types are asset, oracle, compliance, liquidation, and position. For teaching code with realistic dependency handling, copy the closest reference adapter. The scaffold is intentionally incomplete and is not production-ready.

4. Modify

Implement every interface function and document the semantic version, interface revision, factory and owner roles, per-market configuration, external dependencies, decimals and freshness, failure behavior, asset movement, liquidation settlement, and emergency replacement plan. Do not use tx.origin, uncontrolled custody, proxy upgrades behind the adapter address, or permissionless changes to security-critical dependencies.

5. Test

Copy the local adapter environment test and replace the example adapter with yours. It provides mock assets, price feeds, compliance, liquidation, failure cases, and gas measurement.

cd contracts
npm run compile
npx hardhat test test/adapter-environment/AdapterEnvironment.test.ts
npx hardhat test test/unit/<your-adapter>.test.ts
REPORT_GAS=true npx hardhat test test/adapter-environment/AdapterEnvironment.test.ts
npx hardhat coverage
./scripts/check-adapter-submission.sh oracle path/to/MyOracleAdapter.sol

The submission evidence must cover happy path, two-market isolation, unauthorized callers, invalid inputs, unconfigured markets, dependency failure, accounting/reconciliation, reentrancy/CEI, bounded gas, and reproducible version/deployment data. Oracle and compliance adapters require explicit fail-closed tests; liquidation adapters require settlement and surplus tests.

6. Submit

Prepare the deployed address and chain, adapter type, name and version, source commit, interface revision, configuration instructions, supported assets, documentation and repository URIs, dependencies, test results, gas report, limitations, economic assumptions, and emergency contact/runbook.

Register with metadata, starting at Unreviewed. Automated checks are a gate, not a security review. Governance moves the record to In review, then Approved with a review reference or Rejected with a durable reason reference. A Verified mark is not a safety guarantee; a logic change requires a new address, commit, registry entry, and review.

Definition of done

Another developer can clone the source, install dependencies, run the documented commands, understand the adapter’s assumptions and failure modes, reproduce the results from the recorded commit, and explain how the adapter can be deprecated or replaced without silently changing an existing market.