diff --git a/README.md b/README.md
index 61cd89680..45a018116 100644
--- a/README.md
+++ b/README.md
@@ -50,12 +50,12 @@ Transport-agnostic `core` and transport servers for `http`, `ipc`, `websockets`
 
 ```rust
 use jsonrpc_http_server::jsonrpc_core::{IoHandler, Value, Params};
-use jsonrpc_http_server::{ServerBuilder};
+use jsonrpc_http_server::ServerBuilder;
 
 fn main() {
-	let mut io = IoHandler::new();
-	io.add_method("say_hello", |_params: Params| {
-		Ok(Value::String("hello".to_string()))
+	let mut io = IoHandler::default();
+	io.add_method("say_hello", |_params: Params| async {
+		Ok(Value::String("hello".to_owned()))
 	});
 
 	let server = ServerBuilder::new(io)
@@ -97,7 +97,6 @@ fn main() {
 
 ```rust
 use jsonrpc_core_client::transports::local;
-use jsonrpc_core::futures::future::{self, Future, FutureResult};
 use jsonrpc_core::{Error, IoHandler, Result};
 use jsonrpc_derive::rpc;
 
@@ -143,5 +142,4 @@ fn main() {
 	};
 	fut.wait().unwrap();
 }
-
 ```
diff --git a/core/README.md b/core/README.md
deleted file mode 100644
index 13f5e9f64..000000000
--- a/core/README.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# jsonrpc-core
-Transport agnostic rust implementation of JSON-RPC 2.0 Specification.
-
-[Documentation](http://paritytech.github.io/jsonrpc/jsonrpc_core/index.html)
-
-- [x] - server side
-- [x] - client side
-
-## Example
-
-`Cargo.toml`
-
-
-```
-[dependencies]
-jsonrpc-core = "4.0"
-```
-
-`main.rs`
-
-```rust
-use jsonrpc_core::*;
-
-fn main() {
-	let mut io = IoHandler::default();
-	io.add_method("say_hello", |_params: Params| {
-		Ok(Value::String("hello".into()))
-	});
-
-	let request = r#"{"jsonrpc": "2.0", "method": "say_hello", "params": [42, 23], "id": 1}"#;
-	let response = r#"{"jsonrpc":"2.0","result":"hello","id":1}"#;
-
-	assert_eq!(io.handle_request_sync(request), Some(response.to_owned()));
-}
-```
-
-### Asynchronous responses
-
-`main.rs`
-
-```rust
-use jsonrpc_core::*;
-use jsonrpc_core::futures::Future;
-
-fn main() {
-	let io = IoHandler::new();
-	io.add_async_method("say_hello", |_params: Params| {
-		futures::finished(Value::String("hello".into()))
-	});
-
-	let request = r#"{"jsonrpc": "2.0", "method": "say_hello", "params": [42, 23], "id": 1}"#;
-	let response = r#"{"jsonrpc":"2.0","result":"hello","id":1}"#;
-
-	assert_eq!(io.handle_request(request).wait().unwrap(), Some(response.to_owned()));
-}
-```
-
-### Publish-Subscribe
-See examples directory.
diff --git a/derive/examples/client-local.rs b/derive/examples/client-local.rs
new file mode 100644
index 000000000..09a8c0148
--- /dev/null
+++ b/derive/examples/client-local.rs
@@ -0,0 +1,62 @@
+use jsonrpc_core::{
+	futures::{self, FutureExt},
+	BoxFuture, IoHandler, Result,
+};
+use jsonrpc_core_client::transports::local;
+use jsonrpc_derive::rpc;
+
+/// Rpc trait
+#[rpc]
+pub trait Rpc {
+	/// Returns a protocol version
+	#[rpc(name = "protocolVersion")]
+	fn protocol_version(&self) -> Result<String>;
+
+	/// Adds two numbers and returns a result
+	#[rpc(name = "add", alias("callAsyncMetaAlias"))]
+	fn add(&self, a: u64, b: u64) -> Result<u64>;
+
+	/// Performs asynchronous operation
+	#[rpc(name = "callAsync")]
+	fn call(&self, a: u64) -> BoxFuture<Result<String>>;
+}
+
+struct RpcImpl;
+
+impl Rpc for RpcImpl {
+	fn protocol_version(&self) -> Result<String> {
+		Ok("version1".into())
+	}
+
+	fn add(&self, a: u64, b: u64) -> Result<u64> {
+		Ok(a + b)
+	}
+
+	fn call(&self, _: u64) -> BoxFuture<Result<String>> {
+		Box::pin(futures::future::ready(Ok("OK".to_owned())))
+	}
+}
+
+fn main() {
+	futures::executor::block_on(async {
+		let mut io = IoHandler::new();
+		io.extend_with(RpcImpl.to_delegate());
+		println!("Starting local server");
+		let (client, server) = local::connect(io);
+		let client = use_client(client).fuse();
+		let server = server.fuse();
+
+		futures::pin_mut!(client);
+		futures::pin_mut!(server);
+
+		futures::select! {
+			server = server => {},
+			client = client => {},
+		}
+	});
+}
+
+async fn use_client(client: RpcClient) {
+	let res = client.add(5, 6).await.unwrap();
+	println!("5 + 6 = {}", res);
+}
diff --git a/derive/src/lib.rs b/derive/src/lib.rs
index 13cb0fe7b..9f0f50657 100644
--- a/derive/src/lib.rs
+++ b/derive/src/lib.rs
@@ -120,7 +120,22 @@
 //! 	}
 //! }
 //!
-//! # fn main() {}
+//! fn main() {
+//!	  let mut io = jsonrpc_core::MetaIoHandler::default();
+//!	  io.extend_with(RpcImpl::default().to_delegate());
+//!
+//!	  let server_builder = jsonrpc_tcp_server::ServerBuilder::with_meta_extractor(
+//!		io,
+//!		|request: &jsonrpc_tcp_server::RequestContext| Arc::new(Session::new(request.sender.clone()))
+//!	  );
+//!	  let server = server_builder
+//!		.start(&"127.0.0.1:3030".parse().unwrap())
+//!		.expect("Unable to start TCP server");
+//!
+//!   // The server spawns a separate thread. Dropping the `server` handle causes it to close.
+//!   // Uncomment the line below to keep the server running in your example.
+//!	  // server.wait();
+//! }
 //! ```
 //!
 //! Client Example