ERC-2942: EthPM URI Specification


  Ethereum Improvement Proposals
        
        
          
            
              
            
          
        

        AllCoreNetworkingInterfaceERCMetaInformational

      



      
        
  
    

  
    
      🚧 Stagnant
    
    
    
    
    
      Standards Track: ERC
    
  
  
    
      ERC-2942: EthPM URI Specification
    
    
      
        
      
    
    
      
        
      
    
  

  

  	Authors	Nick Gheorghita (@njgheorghita), Piper Merriam (@pipermerriam), g. nicholas d'andrea (@gnidan), Benjamin Hauser (@iamdefinitelyahuman)
	Created	2020-09-04
	Discussion Link	https://ethereum-magicians.org/t/ethpm-v3-specification-working-group/4086/7
	Requires	

  EIP-2678




  


  

  
    Table of Contents

    	Simple Summary
	Abstract
	Specification
	Rationale
	Test Cases
	Implementation
	Security Considerations
	Copyright



  


  
      
      
         Simple Summary
      
      
    

A custom URI scheme to identify an EthPM registry, package, release, or specific contract asset within a release.

  
    
      
      
         Abstract
      
      
    

When interacting with the EthPM ecosystem, users and tooling can benefit from a URI scheme to identify EthPM assets. Being able to specify a package, registry, or release with a single string makes simplifies the steps required to install, publish, or distribute EthPM packages.

  
    
      
      
         Specification
      
      
    

scheme://registry_address[:chain_id][/package_name[@package_version[/json_pointer]]]

  
    
      
      
         scheme
      
      
    

	Required
	Must be one of ethpm or erc1319. If future versions of the EthPM registry standard are designed and published via the ERC process, those ERCs will also be valid schemes.


  
    
      
      
         registry_address
      
      
    

	Required
	This SHOULD be either an ENS name or a 0x-prefixed, checksummed address. ENS names are more suitable for cases where mutability of the underlying asset is acceptable and there is implicit trust in the owner of the name. 0x prefixed addresses are more preferable in higher security cases to avoid needing to trust the controller of the name.


  
    
      
      
         chain_id
      
      
    

	Optional
	Integer representing the chain id on which the registry is located
	If omitted, defaults to 1 (mainnet).


  
    
      
      
         package_name
      
      
    

	Optional
	String of the target package name


  
    
      
      
         package_version
      
      
    

	Optional
	String of the target package version
	If the package version contains any url unsafe characters, they MUST be safely escaped
	Since semver is not strictly enforced by the ethpm spec, if the package_version is omitted from a uri, tooling SHOULD avoid guessing in the face of any ambiguity and present the user with a choice from the available versions.


  
    
      
      
         json_pointer
      
      
    

	Optional
	A path that identifies a specific asset within a versioned package release.
	This path MUST conform to the JSON pointer spec and resolve to an available asset within the package.


  
    
      
      
         Rationale
      
      
    

Most interactions within the EthPM ecosystem benefit from a single-string representation of EthPM assets; from installing a package, to identifying a registry, to distributing a package. A single string that can faithfully represent any kind of EthPM asset, across the mainnet or testnets, reduces the mental overload for new users, minimizes configuration requirements for frameworks, and simplifies distribution of packages for package authors.

  
    
      
      
         Test Cases
      
      
    

A JSON file for testing various URIs can be found in the ethpm-spec repository fixtures.

  
    
      
      
         Implementation
      
      
    

The EthPM URI scheme has been implemented in the following libraries:

	Brownie
	Truffle
	EthPM CLI


  
    
      
      
         Security Considerations
      
      
    

In most cases, an EthPM URI points to an immutable asset, giving full security that the target asset has not been modified. However, in the case where an EthPM URI uses an ENS name as its registry address, it is possible that the ENS name has been redirected to a new registry, in which case the guarantee of immutability no longer exists.

  
    
      
      
         Copyright
      
      
    

Copyright and related rights waived via CC0.


  Citation

  Please cite this document as:

  
  Nick Gheorghita (@njgheorghita), Piper Merriam (@pipermerriam), g. nicholas d'andrea (@gnidan), Benjamin Hauser (@iamdefinitelyahuman), "ERC-2942: EthPM URI Specification [DRAFT]," Ethereum Improvement Proposals, no. 2942, September 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2942.






      
    
  

  

    Ethereum Improvement Proposals


    
      
        	Ethereum Improvement Proposals


      


      	 ethereum/EIPs





      
        Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards.