Merge pull request #55 from ethereumjs/forCustomChain

Add a forCustomChain static factory method

Author: alcuadrado

.gitignore

@@ -68,3 +68,5 @@ node_modules
 package-lock.json
 
 dist
+
+.idea

README.md

@@ -130,11 +130,16 @@ The following chain-specific parameters are provided:
 - `bootstrapNodes` list
 
 To get an overview of the different parameters have a look at one of the chain-specifc
-files like `mainnet.json` in the `chains` directory.
+files like `mainnet.json` in the `chains` directory, or to the `Chain` type in [./src/types.ts](./src/types.ts).
 
-If you want to set up a common instance with parameters for a **private/custom chain** you can pass a
-dictionary - conforming to the parameter format described above - with your custom values in
-the constructor or the `setChain()` method for the `chain` parameter.
+## Working with private/custom chains
+
+There are two ways to set up a common instance with parameters for a private/custom chain:
+
+1. You can pass a dictionary - conforming to the parameter format described above - with your custom values in
+ the constructor or the `setChain()` method for the `chain` parameter.
+
+2. You can base your custom chain's config in a standard one, using the `Common.forCustomChain` method.
 
 # Bootstrap Nodes
 

src/index.ts

@@ -1,5 +1,6 @@
 import { chains as chainParams } from './chains'
 import { hardforks as hardforkChanges } from './hardforks'
+import { Chain } from './types'
 
 interface hardforkOptions {
  /** optional, only allow supported HFs (default: false) */
@@ -14,7 +15,51 @@ interface hardforkOptions {
 export default class Common {
  private _hardfork: string | null
  private _supportedHardforks: Array<string>
- private _chainParams: object
+ private _chainParams: Chain
+
+ /**
+ * Creates a Common object for a custom chain, based on a standard one. It uses all the [[Chain]]
+ * params from [[baseChain]] except the ones overridden in [[customChainParams]].
+ *
+ * @param baseChain The name (`mainnet`) or id (`1`) of a standard chain used to base the custom
+ * chain params on.
+ * @param customChainParams The custom parameters of the chain.
+ * @param hardfork String identifier ('byzantium') for hardfork (optional)
+ * @param supportedHardforks Limit parameter returns to the given hardforks (optional)
+ */
+ static forCustomChain(
+ baseChain: string | number,
+ customChainParams: Partial<Chain>,
+ hardfork?: string | null,
+ supportedHardforks?: Array<string>,
+ ): Common {
+ const standardChainParams = Common._getChainParams(baseChain)
+
+ return new Common(
+ {
+ ...standardChainParams,
+ ...customChainParams,
+ },
+ hardfork,
+ supportedHardforks,
+ )
+ }
+
+ private static _getChainParams(chain: string | number): Chain {
+ if (typeof chain === 'number') {
+ if (chainParams['names'][chain]) {
+ return chainParams[chainParams['names'][chain]]
+ }
+
+ throw new Error(`Chain with ID ${chain} not supported`)
+ }
+
+ if (chainParams[chain]) {
+ return chainParams[chain]
+ }
+
+ throw new Error(`Chain with name ${chain} not supported`)
+ }
 
  /**
  * @constructor
@@ -42,26 +87,16 @@ export default class Common {
  * @returns The dictionary with parameters set as chain
  */
  setChain(chain: string | number | object): any {
- if (typeof chain === 'number') {
- if (chainParams['names'][chain]) {
- this._chainParams = chainParams[chainParams['names'][chain]]
- } else {
- throw new Error(`Chain with ID ${chain} not supported`)
- }
- } else if (typeof chain === 'string') {
- if (chainParams[chain]) {
- this._chainParams = chainParams[chain]
- } else {
- throw new Error(`Chain with name ${chain} not supported`)
- }
+ if (typeof chain === 'number' || typeof chain === 'string') {
+ this._chainParams = Common._getChainParams(chain)
  } else if (typeof chain === 'object') {
  const required = ['networkId', 'genesis', 'hardforks', 'bootstrapNodes']
  for (const param of required) {
  if ((<any>chain)[param] === undefined) {
  throw new Error(`Missing required chain parameter: ${param}`)
  }
  }
- this._chainParams = chain
+ this._chainParams = chain as Chain
  } else {
  throw new Error('Wrong input format')
  }

src/types.ts

@@ -9,5 +9,43 @@ export interface chainsType {
  names: {
  [key: string]: string
  }
- [key: string]: {}
+ [key: string]: any
+}
+
+export interface Chain {
+ name: string
+ chainId: number
+ networkId: number
+ comment: string
+ url: string
+ genesis: GenesisBlock
+ hardforks: Hardfork[]
+ bootstrapNodes: BootstrapNode[]
+}
+
+export interface GenesisBlock {
+ hash: string
+ timestamp: string | null
+ gasLimit: number
+ difficulty: number
+ nonce: string
+ extraData: string
+ stateRoot: string
+}
+
+export interface Hardfork {
+ name: string
+ block: number | null
+ consensus: string
+ finality: any
+}
+
+export interface BootstrapNode {
+ ip: string
+ port: number | string
+ network?: string
+ chainId?: number
+ id: string
+ location: string
+ comment: string
 }

tests/params.ts

@@ -87,4 +87,26 @@ tape('[Common]: Parameter access', function(t: tape.Test) {
  st.comment('-----------------------------------------------------------------')
  st.end()
  })
+
+ t.test('Custom chain usage', function(st: tape.Test) {
+ const mainnetCommon = new Common('mainnet')
+
+ const customChainParams = { name: 'custom', chainId: 123, networkId: 678 }
+ const customChainCommon = Common.forCustomChain('mainnet', customChainParams, 'byzantium')
+
+ // From custom chain params
+ st.equal(customChainCommon.chainName(), customChainParams.name)
+ st.equal(customChainCommon.chainId(), customChainParams.chainId)
+ st.equal(customChainCommon.networkId(), customChainParams.networkId)
+
+ // Fallback params from mainnet
+ st.equal(customChainCommon.genesis(), mainnetCommon.genesis())
+ st.equal(customChainCommon.bootstrapNodes(), mainnetCommon.bootstrapNodes())
+ st.equal(customChainCommon.hardforks(), mainnetCommon.hardforks())
+
+ // Set only to this Common
+ st.equal(customChainCommon.hardfork(), 'byzantium')
+
+ st.end()
+ })
 })