Decentralized Crowdshipping Protocol (Peer-to-Peer Parcel)
This repository contains general-purpose, open-source smart contracts.
The authors and contributors:
- do not operate any delivery service, marketplace, or business built on top of this code
- do not verify or supervise users, carriers, or platforms
- do not provide legal, financial, or tax advice
- are not responsible for deployments, integrations, or real-world usage
All deployments of DeDe Protocol are performed at the risk of the deployer and the integrating platform.
No warranty of any kind is provided.
The software is offered strictly as-is, without guarantees of fitness for any purpose.
The authors are not liable for any damages, losses, claims, or issues arising from the use, misuse, or failure of this software or any derivative work.
By using, deploying, integrating, or interacting with this software in any form, you agree that all responsibility for legal compliance, operation, and outcomes lies solely with you.
DeDe Protocol is finished infrastructure.
The core smart contracts are intentionally minimal, deterministic, and will not be modified, upgraded, or extended. There is no upgrade path, governance mechanism, or maintainer intervention.
DeDe is provided as neutral, general-purpose settlement infrastructure. Its behavior is fully defined by the deployed code and does not depend on any individual, organization, or ongoing development.
All future innovation is expected to happen off-chain or on top of the protocol, without requiring changes to the protocol itself.
DeDe Protocol is a minimal, self-contained, production-ready settlement layer for decentralized delivery networks.
Peer-to-Peer Parcel -> Pickup -> Dropoff -> Delivery confirmation.
DeFi/CeFi Agnostic: Easy integration of delivery settlement for apps, fintech providers, and payment platforms within existing workflows.
This repository contains only the immutable smart contracts, the deploy script, and the mock token used in tests.
Official DeDe Protocol contract addresses:
- ParcelCore: 0xeF1D4970c3B988840B13761Ec4FBb85106d789F8
- Escrow: 0x834317eFB2E6eE362a63474837398086cC302934
- AStarSignerRegistryStaked: 0x311A4c3Ed79D4467C55dd7CEE0C731501DF3f161
- protocolTreasury: 0x9C34d6a6BF1257A9e36758583cDC36F4cE2fA78F
Links to dede-templates repository.
DeDe Multi-Currency DeFI Integration
DeDe Multi-Currency CeFi Integration
.
├── contracts
│ ├── AStarSignerRegistryStaked.sol
│ ├── Escrow.sol
│ └── ParcelCore.sol
├── DeDe-FAQ.md
├── foundry.lock
├── foundry.toml
├── media
│ └── dede.svg
├── README.md
├── script
│ └── DeployProtocol.s.sol
├── test
│ └── MockERC20.sol
└── WHITEPAPER.md
| System Function | Centralized Platforms (Uber / DoorDash / Amazon Flex) | DeDe Protocol (Decentralized Delivery) |
|---|---|---|
| Identity | User identity controlled by the platform | Off-chain identity (wallet, KYC, or none) |
| Matching / Assignment | Platform assigns and controls job visibility | Open matching; integrators choose logic |
| Parcel Lifecycle | Private backend, mutable state | On-chain immutable state machine |
| Escrow / Settlement | Company-controlled funds, reversible payouts | Trustless on-chain escrow, automatic payout |
| Fees | Platform can change fees anytime | Immutable protocol fee + visible platform fee |
| Routing | Proprietary black-box algorithms | Any routing engine (A*, MAPF, ML, custom) |
| Disputes | Opaque centralized arbitration | Auto-finalization + permissionless finalize |
| Data Ownership | Platform owns and monetizes movement + behavioral data | Neutral infrastructure, no data extraction |
DeDe uses NFTs as non-speculative infrastructure, not for art, not for collectibles.
An NFT is simply a globally unique, transferable state container. Unlike fungible assets such as ETH or BTC, an NFT represents exactly one indivisible object and carries authority through ownership.
In DeDe, the parcel NFT binds together:
- parcelId
- lifecycleState
- escrow authority
- encrypted or hashed pickup/dropoff data
- optional route hash and evidence digest
The protocol does not put the physical package on chain. The NFT anchors the parcel’s identity and lifecycle in a public, tamper-resistant state machine.
Possession of the NFT represents the right to advance the parcel lifecycle and finalize settlement. When physical custody changes, authority changes by transferring the token. No identity continuity, account system, or trusted coordinator is required.
This same primitive can apply to:
- Title deeds
- Vehicle ownership
- Event tickets
- Physical access credentials
In all cases, the NFT is not a representation of value or meaning. It is a deterministic capability that binds authority, state, and settlement to a single non-fungible object.
- ERC-721 parcels
- Pickup -> dropoff -> finalize lifecycle
- Automatic finalization after 72h if neither side finalizes
- Immutable Protocol fee (0.5%) paid to
protocolTreasury - Dynamic Platform fee (set by platform provider) paid to
platformTreasury - Permissionless finalization with a 0.05% finalizer tip
- Full slashing support through signer registry
- Emits deterministic events that indexers can build on
- Holds user funds until parcel completion
- Releases value automatically based on parcel state transitions
- Protocol and platform fees are taken at payout time
- Trusted by
ParcelCoreonly
- Permissionless join
- Mandatory stake
- Slashing on misconduct
- Supports A* signatures only
This repo is intentionally bare-metal.
It contains only the canonical protocol implementation.
Apps, UIs, APIs, routing engines, carrier apps, and SDKs live in separate repositories.
-
After
finalizeAfter, anyone may callfinalize(id). -
If parcel is in Dropped or Delivered:
Escrow.releaseWithFeessends funds to carrier, platform treasury, protocol treasury, and finalizer (tip).
-
If parcel is still Minted / Accepted / PickedUp / OutForDelivery and never completed, the platform may dispute or cancel; finalization then refunds the platform if that branch is reached.
-
Parcel state: Finalized.
-
All on-chain fees (protocol fee, platform fee, and finalizer tip) are deducted from the carrier’s payout. The sender never pays settlement fees after funding the escrow.
-
Platform can call
dispute(id, reasonHash)when parcel is Dropped/Delivered. -
Owner (for example, a multisig or DAO) later calls
resolve(id, winner)wherewinneris either the carrier or the platform. -
Depending on resolution:
- If
winner == carrier: funds are released with fees as usual. - Otherwise: full refund to platform.
- If
-
State becomes Finalized and a
Resolvedevent is emitted.
forge install
forge test -vvcp .env.deploy.example .env.deploySet:
PRIVATE_KEYPROTOCOL_TREASURYPLATFORM_TREASURYSTAKE_TOKENMIN_STAKE
anvil
forge script script/DeployProtocol.s.sol:DeployProtocol \
--rpc-url http://127.0.0.1:8545 \
--broadcast \
--env-file .env.deploy-
Protocol fee is immutable and cannot be changed post-deploy
-
Platform fee can be tuned by the platform operator
-
ownerofParcelCoreshould be:- a multisig, or
- a Safe, or
- fully renounced
DeDe Protocol is:
- Minimal
- Permissionless
- Composable
- Neutral
Any routing engine (A*, MAPF, ML, off-chain apps) can plug into it. Any delivery app can adopt it without DeDe adopting your architecture.
DeDe Protocol official, on-chain canonical deployment. This deployment includes the immutable 0.5% Protocol Fee, which supports ongoing audits, tooling, SDKs, and ecosystem maintenance.
Integrators are encouraged to use this official DeDe Protocol deployment because:
-
Security The canonical contracts are audited, publicly inspected, and governed by a multisig.
-
Compatibility Indexers, explorers, and SDKs will follow the official deployment.
-
Sustainability The immutable Protocol Fee funds maintenance without affecting platform economics.
https://github.com/pablo-chacon/dede-templates
Most platforms should use the canonical deployment. However, advanced users, researchers, and private test networks may deploy their own instance.
forge script script/DeployProtocol.s.sol:DeployProtocol \
--rpc-url $SEPOLIA_RPC \
--broadcast \
--env-file .env.deployforge script script/DeployProtocol.s.sol:DeployProtocol \
--rpc-url $MAINNET_RPC \
--broadcast \
--legacy \
--gas-price $(cast --to-wei 15 gwei) \
--env-file .env.deployCustom deployments will not be indexed alongside the canonical DeDe contracts and will not automatically inherit ecosystem tooling.
MIT License
Copyright (c) 2025 Emil Karlsson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.